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

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":"123",
    "clientSecret":"123"
}

Example response

{
    "accessToken": "123"
}

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

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!

Rate limiting

By default requests are limited to 5 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. All problems with the request are returned in standardized list of errors.

This is the response of from trying to create a case with an invalid date for the dob:

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

Polling vs webhooks

A lot of processing in the EyeDP platform 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.

There's two ways to get the results of these types of jobs: Polling or Webhooks. Unfortunately we don't have webhooks yet so polling is the only option.