This page describes main features of iDelegate’s API implementation.
Application Programming Interfaces (APIs) serve to link up different software applications. Through iDelegate API your developers are able to access iDelegate database programmatically to include its data in your own applications. iDelegate API is only available with Enterprise contract.
Contents
1. API reference
2. Authentication
3. Errors
4. Resource objects
5. Retrieve data
6. Filter data
7. Complete request – response example
API reference
The iDelegate API is organised around REST. It has resource-oriented URLs, uses standard HTTP response codes and authentication, and returns JSON-encoded responses.
Authentication
The iDelegate API uses access tokens to authenticate requests. Your iDelegate administrator can create an API User and generate access tokens in their iDelegate dashboard.
Attention
API keys may carry many privileges, and so must be kept secure! Do not share secret API keys in publicly accessible areas such as GitHub, shared code or similar.
API requests without authentication will fail.
Errors
iDelegate uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a resource was not found). Codes in the 5xx range indicate a server error.
Most errors will include a message that briefly explains the error reported.
Error Response
{
“status”: 404,
“message”: “Wrong number. The requested API endpoint does not exist.”
}
Resource objects
iDelegate API has three resource objects. These are Users, Delegations and Issuances. See complete response – request example how these three fit together.
4.1 The User object
User is the principal object retrieved through the iDelegate API. Through it you can access iDelegation users, their delegations, authorities granted and limits of those authorities.
The User Object
{
“name”: “Kirill Derevenski”,
“email”: “kirill@idelegate.io”,
“position”: “Founder”,
“entityName”: “iDelegate”,
“role”: “Delegate”,
…
“delegations”: []
}
4.2 The Delegation object
Delegation object is a ‘sidecar’ to the User object and retrieved together with the User object when requested through API parameters.
The Delegation Object
{
“policy”: “Delegation of Authority Policy”,
“currency”: “USD”,
“title”: “Operational Delegation”,
“delegatorComment”: “With great power comes great responsibility.”,
“delegateComment”: “I will use it wisely!”,
“temporary”: false,
“validUntil”: “2025-06-30T10:00:00.000000Z”,
…
“issuances”: []
}
4.3 The Issuance object
Issuance object is a ‘sidecar’ to the Delegation object. It is always retrieved with the Delegation object.
The Issuance Object
{
“authorityDescription”: “Approve CAPEX within overall budget”,
“globalRemarks”: “Per transaction”,
“globalRaci”: “Investment Committee pre-approves”,
“delegatedLimit”: “1000000.00”,
“currency”: “USD”,
…
}
iDelegate objects contain many attributes. Detailed object attributes can be supplied to your developers on request.
Retrieve data
You retrieve data by sending a request to the iDelegate API endpoint. You must provide a valid access token to receive a practical response. Any API request without authentication will fail.
Endpoint
GET api/v1/users
You can vary parametrically amount and/or extent of data retrieved through the iDelegate API. See 6. Filter data for guidance.
5.1 Retrieve all users
By default, sending an authenticated request to the iDelegate API endpoint will return a collection of User objects.
Request: All users
GET api/v1/users
To retrieve all users with their delegations, send withDelegations=true to the API endpoint.
Request: All users with delegations
GET api/v1/users?withDelegations=true
5.2 Retrieve one user
You can retrieve an individual User object by sending their iDelegate user id to the API endpoint.
Request: Specific user
GET api/v1/users/:userId
To retrieve a single user with their delegations, send withDelegations=true to the API endpoint.
Request: Specific user with delegation(s)
GET api/v1/users/:userId?withDelegations=true
Filter data
You can filter users at the iDelegate end and retrieve only filtered User objects by sending filterable parameters to the API endpoint. Filterable parameters are: email, entityId and role.
Request: Retrieve users filtered by role and entity id
GET api/v1/users?role[eq]=delegate&entityId[eq]=1
The email and role parameters support only the [eq] operator. The entityId parameter supports any of the [eq, ne, lt, gt, lte, gte] operators.
Note that the parametric filter query is exclusively an AND query.
You can chain withDelegations=true to retrieve user delegations at the same time.
Complete request-response example
If user’s iDelegate and your app emails match (which is usually the case in corporate environment and certainly so if Single Sign On is also used), you may find it easier to grab a specific user by filtering on their email address.
Request: Retrieve user with delegation(s) by email filter
GET api/v1/users?email[eq]=kirill@idelegate.io&withDelegations=true
Sending the above request to the iDelegate API will return a User object complete with associated delegations and issuances.
Response: Retrieve user with delegation(s) by email filter
{
“name”: “Kirill Derevenski”,
“email”: “kirill@idelegate.io”,
“position”: “Founder”,
“entityName”: “iDelegate”,
“role”: “Delegate”,
…
“delegations”: [
{
“policy”: “Delegation of Authority Policy”,
“currency”: “USD”,
“title”: “Operational Delegation”,
“delegatorComment”: “With great power comes great responsibility.”,
“delegateComment”: “I will use it wisely!”,
“temporary”: false,
“validUntil”: “2025-06-30T10:00:00.000000Z”,
…
“issuances”: [
{
“authorityDescription”: “Approve investments within overall budget”,
“globalRemarks”: “Per transaction”,
“globalRaci”: “Board pre-approves”,
“delegatedLimit”: “10000.00”,
“currency”: “USD”,
…
},
{
“authorityDescription”: “Sign commercial agreements and contracts”,
“globalRemarks”: “Per individual agreement or contract”,
“globalRaci”: “Legal consulted. Finance informed”,
“delegatedLimit”: “75000.00”,
“currency”: “USD”,
…
}
]
}
]
}