API basics

All the things on a developer checklist when you're integrating a new API

Environments

We have two environments. Sandbox for setting up and testing your integration. Production for live traffic.

Name	URL	Description
Sandbox	https://api-sandbox.eyedp.com	Setup and integration testing with fake checks
Production	https://api.eyedp.com	Live traffic with real checks

The sandbox is intended for testing and development purposes only. Availability is not guaranteed and may be affected by maintenance, updates, or system load.

Authentication

The eyeDP api uses the oAuth client credentials flow for authentication.

First generate an access token using a client id and client secret. Then use that token for calling api endpoints. Access tokens are valid for 60 minutes.

Generating a token

Method: POST

Endpoint: /api/authenticate

Example request

{
    "clientId":"YOUR_CLIENT_ID",
    "clientSecret":"YOUR_CLIENT_SECRET"
}

Copy-pasteable curl against sandbox (replace the placeholders with the credentials you were sent at onboarding):

curl -X POST https://api-sandbox.eyedp.com/api/authenticate \
  -H "Content-Type: application/json" \
  -d "{\"clientId\":\"YOUR_CLIENT_ID\",\"clientSecret\":\"YOUR_CLIENT_SECRET\"}"

Example response

{
    "accessToken": "eyJhbGciOi...",
    "expires": 3600
}

expires is the token lifetime in seconds (60 minutes).

If required fields are missing, ASP.NET returns a field-validation dictionary instead of the errors list used elsewhere:

{
    "ClientId": [
        "The ClientId field is required."
    ],
    "ClientSecret": [
        "The ClientSecret field is required."
    ]
}

Using the token

The access token must be included in all other api calls. Include it by putting

Header name	Value
Authorization	Bearer your-token

How to get a client id and secret

You will be sent credentials during onboarding. We will be making this self service soon!

Open Api

The api has a full open API spec ready to import into Postman or code generation tools:

https://api.eyedp.com/swagger

Postman

We've created a basic Postman collection to help get you get started with our API.

You can export it from our Postman page.

Webhooks

The EyeDP platform is event driven and a lot of work happens in background jobs. The results from jobs such as document extraction or document risk checks won't be available immediately or returned straight away from your requests.

For these reasons webhooks are an important part of the platform. It's how we notify your system of jobs finishing and results being available.

Webhooks are fully configurable through the API. Please see the webhooks endpoint page for more details.

Versioning

The api uses semantic versioning to give you control on how you want to handle api changes.

Minor version increases signify changes to the open api spec like additional properties on an object or a new endpoint being added. Major version increases are for breaking changes like objects removed from the open api spec.

Specify an api version by passing it in a api-version query parameter. Any requests sent without a specified version will default to the latest. We highly recommend specifying a version so you don't encounter unexpected changes from the api.

Version example request: https://api-sandbox.eyedp.com/api/cases/123?api-version=1.0

Version history

Date	Version	Notes
01/05/2025	1.0	Here we go!

Ping

Authenticated GET /api/Ping returns "Pong". Use it as a connectivity check once you have a token.

curl https://api-sandbox.eyedp.com/api/Ping \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate limiting

By default requests are limited to 15 per second.

Custom arrangements can be made, please contact us if you require more.

Bad requests

Bad requests are returned when there is something wrong with the request. Most API errors use a standardized list of errors:

{
    "errors": [
        "Date of birth is not a valid date"
    ]
}

This is the response from trying to create a case with an invalid date of birth.

Missing required fields on some endpoints (including authenticate) instead return an ASP.NET field-validation dictionary, keyed by property name:

{
    "ClientId": [
        "The ClientId field is required."
    ]
}