Individual

Represent the Know you customer (KYC) related part of the Synaps API

Session details

Once your session is initialized using initialize session endpoint you can retrieve the current state of the session by calling the get session details endpoint.

GET/v4/individual/session/{id}

Get session details

This endpoint allows you to retrieve the current state of a KYC session.

Request

Name
Api-Key
Type
string
Description
The API key to used for authentication.

Path

Name
id
Type
object
Description
The session identifier. returned by the init session endpoint.

Request

GET

/v4/individual/session/{id}


curl --location -g --request GET 'https://api.synaps.io/v4/individual/session/{id}' \
--header 'Api-Key: YOUR_API_KEY'

Response

Name
app
Type
object
Description
The application linked to the session
Name
app.name
Type
string
Description
The application public name
Name
app.id
Type
number
Description
The application internal identifier

Name
session
Type
object
Description
Your requested session data.
Name
session.alias
Type
string
Description
The session alias.
Name
session.id
Type
string
Description
The session identifier.
Name
session.status
Type
string
Description
One of
- APPROVED
- REJECTED
- RESUBMISSION_REQUIRED
- SUBMISSION_REQUIRED
- PENDING_VERIFICATION
Name
session.sandbox
Type
bool
Description
Indicates if the session is in sandbox mode.
Name
session.steps
Type
[]object
Description
An array of steps.
Name
session.steps.id
Type
number
Description
The step identifier, used in the step details endpoint.
Name
session.steps.status
Type
string
Description
The step identifier, used in the step details endpoint.
Name
session.steps.type
Type
string
Description
The step type, one of:
- ID_DOCUMENT
- LIVENESS
- PROOF_OF_ADDRESS
- PHONE
- EMAIL
- PVID (BETA)

{
  "app": {
    "name": "YOUR_APP_NAME",
    "id": "16316066"
  },
  "session": {
    "alias": "YOUR_SESSION_ALIAS",
    "id": "9a00701c-fa82-4e8a-9054-5412b4bc889d",
    "status": "SUBMISSION_REQUIRED",
    "sandbox": false,
    "steps": [
      {
        "id": "163133663329",
        "status": "SUBMISSION_REQUIRED",
        "type": "LIVENESS"
      },
      {
        "id": "163160112665",
        "status": "SUBMISSION_REQUIRED",
        "type": "ID_DOCUMENT"
      }
    ]
  }
}

Verification Step

Represent a verification step of an user's KYC.

GET/v4/individual/session/{session_id}/step/{step_id}

Get step details

You can fetch a specific step details by calling the following endpoint.

Request

Header

Name
Api-Key
Type
string
Description
The API key to used for authentication.

Path

Name
session_id
Type
string
Description
The session identifier. returned by the init session endpoint.
Name
step_id
Type
string
Description
The step identifier. returned by the get session details endpoint.

GET

/v4/individual/session/{session_id}/step/{step_id}

curl --location -g --request GET 'https://api.synaps.io/v4/individual/session/{id}/step/{step_id}' \
--header 'Api-Key: {YOUR_API_KEY}'

Response

All steps response share the same common payload

All step specific payloads are described below:

Common Payload

Name
id
Type
number
Description
Name
type
Type
string
Description
The step type.
One of
- ID_DOCUMENT
- LIVENESS
- PROOF_OF_ADDRESS
- PHONE
- EMAIL
- PVID (BETA)
Name
metadata
Type
object
Description
All kind of metadata linked to the step.
Name
status
Type
string
Description
A step status.

Name
reason
Type
?object
Description
The reason of Rejection.
Not null if status == REJECTED.
Name
reason.code
Type
string
Description
One of reasons code.
Name
reason.message
Type
object
Description
The rejection message.
Name
reason.message.original
Type
string
Description
The original message written by one of our agent.
Name
reason.message.translated
Type
string
Description
The translated message.

{
  "id": "163160662111",
  "type": "ID_DOCUMENT",
  "metadata": {
    "ip": "233.22.11.11",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel ...",
    "platform": "Intel Mac OS X 10.15",
    "browser_name": "Firefox",
    "browser_version": "114.0",
    "device": "",
    "customer_language": ""
  },
  "status": "APPROVED", // REJECTED | RESUBMISSION_REQUIRED | SUBMISSION_REQUIRED | APPROVED | PENDING_VERIFICATION
  "reason": null, // Only if status == "REJECTED"
  ...
}

ID_DOCUMENT

Name
document
Type
object
Description
The ID document available data
Name
document.country
Type
string(ISO-3166)
Description
An ISO-3166 country code
Name
document.type
Type
string
Description
One of
- PASSPORT
- NATIONAL_ID
- DRIVER_LICENSE
- RESIDENT_PERMIT
Name
document.fields
Type
object
Description
Extracted document fields, content depends of the document.type.

Name
document.files
Type
object
Description
The document files front, face (and back if available).
Theses files are processed on the Synaps side. If you want, the original files, you should use original_files field instead.
Name
document.files.front
Type
file
Description
The front file data if available.
Name
document.files.back
Type
file
Description
The front file data if available.
Name
document.files.face
Type
file
Description
The document extracted face file data if available.

Name
document.original_files
Type
object
Description
The originally uploaded document front (and back if available) files.
Name
document.original_files.front
Type
file
Description
The originally uploaded front file data if available.
Name
document.original_files.back
Type
file
Description
The originally uploaded front file data if available.

{
  ...
  "document": {
    "country": "FRA", // ISO-3166
    "type": "PASSPORT", // PASSPORT | ID_DOCUMENT | DRIVER_LICENSE | RESIDENT_PERMIT
    "fields": {
      "firstname": "NATACHA",
      "lastname": "SPECIMEN",
      "birth_date": "1953-07-12",
      "document_expiration": "2024-02-23",
      "document_number": "60RF00811",
      "nationality": "FRA"
    },
    "files": {
      "front": { ... },
      "back": { ... },
      "face": { ... }
    },
    "original_files": {
      "front": { ... },
      "back": { ... }
    }
  }
}

LIVENESS

Name
verification
Type
object
Description
The liveness verification data.
Name
verification.liveness
Type
object
Description
The liveness verification data.
Name
verification.liveness.file
Type
file
Description
The liveness file data.

{
  ...
  "verification": {
    "liveness": {
      "file": {
        "url": "https://picsum.photos/200",
        "type": "image/jpeg",
        "size": 44343
      }
    }
  }
}

PHONE

Name
verification
Type
object
Description
The phone verification data.
Name
verification.phone
Type
object
Description
The step verification data.
Name
verification.phone.number
Type
string
Description
The step phone number.
Name
verification.phone.calling_code
Type
string
Description
The step phone number calling code.
Name
verification.phone.method
Type
string
Description
The method used to verify the phone number.
One of
- sms
- call
Name
verification.phone.country
Type
string(ISO-3166)
Description
The step country.

{
  ...
  "verification": {
    "phone": {
      "number": "+33686521748",
      "calling_code": "33",
      "method": "sms",
      "country": "FRA"
    }
  }
}

EMAIL

Name
verification
Type
object
Description
The email verification data.
Name
verification.email
Type
object
Description
The email data.
Name
verification.email.value
Type
string
Description
The email value.

{
    ...
    "verification": {
        "email": {
            "value": "john@synaps.io"
        }
    }
}

PROOF_OF_ADDRESS

Name
document
Type
object
Description
The POA verification data.
Name
document.country
Type
string(ISO-3166)
Description
The POA country.
Name
document.type
Type
string
Description
One of
- ELECTRICITY_BILL
- INTERNET_BILL
- LANDLINE_BILL
- WATER_BILL
- GAS_BILL
- BANK_STATEMENT
Name
document.host_id_document
Type
object
Description
The document of the host object.
Only present if the documentation requires a proof of accomodation.

Name
document.files
Type
object
Description
All processed POA files.
Name
document.files.proof
Type
object
Description
The proof file.
Name
document.files.accomodation
Type
object
Description
The accomodation file.

Name
document.original_files
Type
object
Description
The original files.
Name
document.original_files.proof
Type
object
Description
The original proof file.
Name
document.original_files.accomodation
Type
object
Description
The original accomodation file.

Name
document.fields
Type
object
Description
The fields of the POA document.
Name
document.fields.address
Type
string
Description
The address of the document.
Name
document.fields.city
Type
string
Description
The city of the document.
Name
document.fields.zipcode
Type
string
Description
The zipcode of the document.
Name
document.fields.issuing_date
Type
string
Description
The issuing data of the document if it exist.
Otherwise it will be empty.

{
  ...
  "document": {
    "country": "FRA",
    "type": "INTERNET_BILL",
    "host_id_document": { ... },
    "files": {
      "proof": { ... },
      "accomodation": { ... }
    },
    "original_files": {
      "proof": { ... },
      "accomodation": { ... }
    },
    "fields": {
      "address": "70 rue de la paix",
      "city": "Paris",
      "zipcode": "75000",
      "issuing_date": ""
    }
  }
}

PVID

Name
document
Type
object
Description
The PVID verification data.
Name
document.country
Type
string(ISO-3166)
Description
The ID document country.
Name
document.type
Type
string
Description
One of
- PASSPORT
- NATIONAL_ID
- DRIVER_LICENSE
- RESIDENT_PERMIT
Name
document.face
Type
object
Description
Face file.

Name
document.files
Type
object
Description
The ID document files.
Name
document.files.front
Type
object
Description
Front document file.
Name
document.files.back
Type
object
Description
Back document file.

Name
document.fields
Type
object
Description
The fields of the ID document.
Name
document.fields.firstname
Type
string
Description
The firstname of the user.
Name
document.fields.lastname
Type
string
Description
The lastname of the user.
Name
document.fields.birth_date
Type
string(YYYY-MM-DD)
Description
The birth date of the user.
Name
document.fields.document_expiration
Type
string(YYYY-MM-DD)
Description
The document expiration of the document.
Name
document.fields.document_number
Type
string
Description
The document number of the document.
Name
document.fields.nationality
Type
string(ISO-3166)
Description
The nationality of the user.
Name
document.fields.gender
Type
string
Description
The gender of the user. One of
- M
- F
Name
document.fields.birth_place
Type
string
Description
The birth place of the user.
Name
document.fields.full_name
Type
string
Description
The full name of the user.

{
  ...
  "document": {
    "country": "FRA",
    "type": "NATIONAL_ID",
    "files": {
      "front": {
        "url": "",
        "type": "image/png",
        "size": 1232
      },
      "back": { ... }
    },
    "face": {
        "url": "",
        "type": "image/png",
        "size": 1232
    },
    "fields": {
      "firstname": "John",
      "lastname": "Doe",
      "birth_date": "1953-07-12",
      "document_expiration": "2024-02-23",
      "document_number": "60RF00811",
      "nationality": "FRA",
      "gender": "M",
      "birth_place": "Paris",
      "full_name": "John Doe"
    }
  }
}

DUPLICATE

DUP is a substep of the ID_DOCUMENT step.
The DUP step_id is the ID_DOCUMENT stepID with the suffix :DUP.

For example: ID163160112665:DUP

Name
verification
Type
object
Description
The duplicate verification data.
Name
verification.duplicate
Type
object
Description
Duplicate data.
Name
verification.duplicate.face
Type
object
Description
Presigned URL of the face to download. (available for 15 minutes)
Name
verification.duplicate.matches
Type
object[]
Description
An array of matches objects containing various information.

{
  ...
  "verification": {
    "duplicate": {
      "face": "https://document-to-download.com",
      "matches": [{
        "face": "https://document-to-download.com",
        "session_id": "9a00701c-fa82-4e8a-9054-123aaa12",
        "similarity_score": 0.23,
      },
      {
        "face": "https://document-to-download.com",
        "session_id": "9a00701c-fa82-4e8a-9054-123aaa12",
        "similarity_score": 0.23,
      }]
    }
  }
}

AML

AML is a substep of the ID_DOCUMENT step.
The AML step_id is the ID_DOCUMENT stepID with the suffix :AML.

For example: ID163160112665:AML

Name
verification
Type
object
Description
The AML verification data.
Name
verification.aml
Type
object
Description
AML data.
Name
verification.aml.customer_info
Type
object
Description
AML customer infos.
Name
verification.aml.hits
Type
object[]
Description
An array of hit objects containing various information.
Name
verification.aml.total_hits
Type
number
Description
Total number of hits.
Name
verification.aml.action_required
Type
boolean
Description
Indicates whether action is required.
Name
verification.aml.monitored
Type
boolean
Description
Indicates whether the AML monitoring is enabled.

{
  ...
  "verification": {
    "aml": {
      "customer_info": {
        "firstname": "NICOLAS",
        "lastname": "SARKOZY",
        "birth_date": "1953-07-12",
        "nationality": "FRA",
        "country": "FRA"
      },
      "hits": [
        {
          "fields": [],
          "aliases": [
            "Nicolas Sarkozy"
          ],
          "media": [
            {
              "date": "",
              "snippet": ": da una parte il processo per corruzione a Nicolas Sarkozy,\\u00a0dall'altra la nuova bufera su\\u00a0Fran\\u00e7ois Hollande. I giudici che indagano sul tentativo di corruzione di un giudice da parte dell'ex presidente francese potranno utilizzare le intercettazioni di telefonate fra lo stesso Sarkozy (che si faceva chiamare con [...]<\\/p>\\n\",\"protected\"",
              "title": "(no title)",
              "url": "https://www.secoloditalia.it/wp-json/wp/v2/posts/265010"
            }
          ],
          "info": {
            "full_name": "Nicolas Sarkozy",
            "birth_date": "N/A",
            "nationality": "Italy"
          },
          "type": [
            "ADVERSE_MEDIA"
          ]
        }
      ],
      "total_hits": 1,
      "action_required": false,
      "monitored": false
  }
}