Corporate

Represent the Know you business (KYB) 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/corporate/session/{id}

Get session details

This endpoint allows you to retrieve the current state of a KYB 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/corporate/session/{id}


curl --location -g --request GET 'https://api.synaps.io/v4/corporate/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.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:

{
  "app": {
    "name": "YOUR_APP_NAME",
    "id": "16316066"
  },
  "session": {
    "alias": "YOUR_SESSION_ALIAS",
    "id": "9a00701c-fa82-4e8a-9054-5412b4bc889d",
    "status": "SUBMISSION_REQUIRED",
    "sandbox": false,
    "steps": [
      {
        "status": "APPROVED",
        "type": "COMPANY_DETAILS"
      },
      {
        "status": "SUBMISSION_REQUIRED",
        "type": "LEGAL_REPRESENTATIVE"
      }
      ...
    ]
  }
}

Verification Step

Represent a verification step of an user's KYB.

GET/v4/corporate/session/{session_id}/step/{step_type}

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_type
Type
string
Description
The step type. returned by the get session details endpoint.

GET

/v4/corporate/session/{session_id}/step/{step_type}

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

Response

DOCUMENTS

Name
certificate_of_incorporation
Type
object
Description
The certificate of incorporation document available data
Name
certificate_of_incorporation.files
Type
object[]
Description
The certificate of incorporation files provided by user, if available.
Name
certificate_of_incorporation.status
Type
string
Description
The certification of incorporate verification status.

Name
memorandum_of_association
Type
object
Description
The memorandum of association document available data
Name
memorandum_of_association.files
Type
object[]
Description
The memorandum of association files provided by user, if available.
Name
memorandum_of_association.status
Type
string
Description
The memorandom of association verification status.

Name
register_of_directors_and_shareholders
Type
object
Description
The register of directors and shareholders document available data
Name
registry_of_directors_and_shareholders.files
Type
object[]
Description
The registry of directors and shareholders files provided by user, if available.
Name
registry_of_directors_and_shareholders.status
Type
string
Description
The registry of directors and shareholders verification status.

{
  "certificate_of_incorporation": {
    "files": [
      {
        "url": "https://picsum.photos/200",
        "type": "image/jpeg",
        "size": 44343
      }
    ],
    "status": "APPROVED"
  },
  "memorandum_of_association": {
    "files": [
      ...
    ],
    "status": "PENDING_VERIFICATION"
  },
  "registry_of_directors_and_shareholders": {
    "files": [
      ...
    ],
    "status": "REJECTED"
  }
}

LEGAL_REPRESENTATIVE

Name
id
Type
string
Description
The ID of the legal representative
Name
firstname
Type
string
Description
The firstname of the legal representative
Name
lastname
Type
string
Description
The lastname of the legal representative
Name
birth_date
Type
string
Description
The birth date of the legal representative
Name
nationality
Type
string
Description
The nationality of the legal representative
Name
status
Type
string
Description
The global status of the legal representative step.

Name
authorization
Type
object
Description
The authorization information for the legal representative.
Name
authorization.required
Type
bool
Description
Indicates whether authorization is required.
Name
authorization.file
Type
object
Description
The authorization file data if available.

Name
steps
Type
object[]
Description
An array of individual steps associated with the legal representative. Represent KYC steps of the legal representative.
Name
steps.id
Type
string
Description
KYC step identifier
Name
steps.status
Type
string
Description
KYC step status

{
  "id": "123456",
  "firstname": "John",
  "lastname": "Doe",
  "birth_date": "1985-05-20",
  "nationality": "USA",
  "authorization": {
    "required": true,
    "file": { ... }
  },
  "steps": [
    {
      "id": "163133663329",
      "status": "APPROVED",
      "type": "LIVENESS"
    },
    {
      "id": "16323233329",
      "status": "PENDING_VERIFICATION",
      "type": "AML"
    },
    ...
  ],
  "status": "PENDING_VERIFICATION"
}

COMPANY_DETAILS

Name
name
Type
string
Description
The name of the company
Name
city
Type
string
Description
The city where the company is located
Name
country
Type
string
Description
The country where the company is located
Name
address
Type
string
Description
The address of the company
Name
zipcode
Type
string
Description
The zipcode of the company's location
Name
registration_number
Type
string
Description
The registration number of the company
Name
structure
Type
string
Description
The structure type of the company

{
  "name": "Example Company",
  "city": "Example City",
  "country": "Example Country",
  "address": "123 Example Street",
  "zipcode": "12345",
  "registration_number": "ABC123",
  "structure": "Example Structure"
}

AML

Name
action_required
Type
bool
Description
Indicates whether action is required.
Name
matches
Type
int
Description
The number of matches found.
Name
status
Type
string
Description
The status information for AML screening.
Name
monitoring
Type
bool
Description
Indicates whether monitoring is required.

Name
screening
Type
object[]
Description
An array of AML screening results.
Name
screening.id
Type
string
Description
The unique identifier for the screening entry.
Name
screening.info
Type
object
Description
Information related to the screening entry, including full name, entity type, aliases (AKA), countries, birth date, and associates.
Name
screening.sanctions
Type
object[]
Description
An array of sanctions associated with the screening entry.
Name
screening.pep
Type
object[]
Description
An array of Politically Exposed Persons (PEP) associated with the screening entry.
Name
screening.adverse_media
Type
object[]
Description
An array of adverse media reports related to the screening entry, including date, snippet, title, and URL.
Name
screening.types
Type
string[]
Description
An array of types associated with the screening entry.

Name
decision
Type
object
Description
The decision information for AML screening.
Name
decision.compliance_officer
Type
string
Description
The compliance officer responsible for the decision.
Name
decision.user_id
Type
string
Description
The user ID associated with the decision.
Name
decision.output
Type
string
Description
The output or decision result.
Name
decision.internal_note
Type
string
Description
Internal notes or comments related to the decision.
Name
decision.reasons
Type
object[]
Description
An array of reasons for the decision, including the reason and accompanying notes.

{
  "action_required": true,
  "matches": 5,
  "screening": [
    {
      "id": "1",
      "info": {
        "full_name": "John Doe",
        "entity_type": "Individual",
        "aka": ["Doe, John"],
        "countries": "US",
        "birth_date": "1980-01-01",
        "associates": [
          {
            "association": "Director",
            "name": "Jane Smith"
          }
        ]
      },
      "sanctions": [
        {
          "types": ["Sanctions", "PEP"],
          "countries": [
            {
              "country_code": "US",
              "name": "United States"
            }
          ],
          "name": "John Doe",
          "url": "https://example.com/johndoe",
          "listing_ended": "2023-01-01",
          "listing_started": "2022-01-01",
          "fields": [
            {
              "name": "Source",
              "value": "OFAC"
            },
            { ... }
          ]
        }
      ],
      "pep": [
        {
          "types": ["Sanctions", "PEP"],
          "countries": [
            {
              "country_code": "US",
              "name": "United States"
            }
          ],
          "name": "Jane Smith",
          "url": "https://example.com/janesmith",
          "listing_ended": "2023-02-01",
          "listing_started": "2022-02-01",
          "fields": [
            {
              "name": "Source",
              "value": "OFAC"
            },
            { ... }
          ]
        }
      ],
      "adverse_media": [
        {
          "date": "2023-03-01",
          "snippet": "Adverse media snippet...",
          "title": "Adverse Media Report",
          "url": "https://example.com/adverse"
        }
      ],
      "types": ["AML"]
    },
    { ... }
  ],
  "status": "REJECTED",
  "decision": {
    "compliance_officer": "...",
    "user_id": "123",
    "output": "Proceed with caution",
    "internal_note": "High risk profile",
    "reasons": [
      {
        "reason": "Sanctions match",
        "note": "Potential risk"
      },
      { ... }
    ]
  },
  "monitoring": false
}

BENEFICIAL_OWNERS

Name
individuals
Type
object[]
Description
Individual beneficial owners associated with the company.
Name
individuals.node_id
Type
int
Description
The unique identifier for the individual entity.
Name
individuals.firstname
Type
string
Description
The firstname of the individual.
Name
individuals.lastname
Type
string
Description
The lastname of the individual.
Name
individuals.birth_date
Type
string
Description
The birth date of the individual.
Name
individuals.nationality
Type
string
Description
The nationality of the individual.
Name
individuals.ultimate
Type
bool
Description
Indicates whether the individual is an ultimate entity.
Name
individuals.links
Type
object[]
Description
An array of Edge objects representing relationships or connections to other entities. See Edge structure for details.
Name
individuals.id
Type
string
Description
The unique identifier for the individual.
Name
individuals.steps
Type
object[]
Description
An array of step objects representing verification steps associated with the individual.
Name
individuals.steps.id
Type
string
Description
KYC step identifier
Name
individuals.steps.type
Type
string
Description
KYC step type, one of:
Name
individuals.steps.status
Type
string
Description
KYC step status
Name
individuals.status
Type
string
Description
The status of the individual entity. See Status for details.
Name
individuals.edges
Type
object[]
Description
An array of Edge objects representing relationships or connections to other entities. See Edge structure for details.

Name
corporate
Type
object[]
Description
Corporate beneficial owners associated with the company.
Name
corporates.node_id
Type
int
Description
The unique identifier for the corporate entity.
Name
corporates.company_details
Type
object
Description
The details of the company associated with this corporate entity. See the structure for details.
Name
corporates.aml
Type
object
Description
Anti-Money Laundering (AML) step response information. See the structure for details.
Name
corporates.documents
Type
object
Description
A collection of documents associated with the corporate entity. Each document is identified by a string key, and the value is a Document object. See structure for details.
Name
corporates.edges
Type
object[]
Description
An array of Edge objects representing relationships or connections to other entities.

{
  "corporates": [
    {
      "node_id": 1,
      "company_details": {
        "name": "Anima",
        "city": "Paris",
        "country": "FRA",
        "address": "4 rue de la paix",
        "zipecode": "75000",
        "registration_number": "12D8931S",
        "structure": "SAS",
      },
      "aml": {},
      "documents": {
        "CERTIFICATE_OF_INCORPORATION": {
          "files": [
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            },
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            }
          ],
          "status": "APPROVED"
        },
        "MEMORANDUM_OF_ASSOCIATION": {
          "files": [
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            },
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            }
          ],
          "status": "VALIDATED"
        },
        "REGISTER_OF_DIRECTORS_SHAREHOLDERS": {
          "files": [
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            },
            {
              "url": "https://picsum.photos/200",
              "type": "image/jpeg",
              "size": 10120
            }
          ],
          "status": "VALIDATED"
        }
      },
      "edges": [
        {
          "node_id": 0,
          "shares": 20.9,
          "director": true
        }
      ]
    }
  ],
    "individuals": [
      {
        "node_id": 1,
        "firstname": "NATACHA",
        "lastname": "SPECIMEN",
        "birth_date": "1953-07-12",
        "nationality": "FRA",
        "ultimate": true,
        "edges": [
          {
            "node_id": 0,
            "shares": 42.5,
            "director": true
          },
          {
            "node_id": 1,
            "shares": 90,
            "director": false
          }
        ],
        "id": "eazdad",
        "steps": [
          {
            "id": "163160112665",
            "status": "SUBMISSION_REQUIRED",
            "type": "ID_DOCUMENT"
          },
          {
            "id": "133160112665",
            "status": "SUBMISSION_REQUIRED",
            "type": "PROOF_OF_ADDRESS"
          },
          {
            "id": "133160112665",
            "status": "APPROVED",
            "type": "AML"
          }
        ],
        "status": "SUBMISSION_REQUIRED"
      },
      {
        "node_id": 2,
        "ultimate": false,
        "firstname": "NATACHA",
        "lastname": "SPECIMEN",
        "birth_date": "1953-07-12",
        "nationality": "FRA",
        "links": [
          {
            "node_id": 1,
            "shares": 10,
            "director": false
          }
        ],
        "id": "eazdad",
        "steps": [
          {
            "id": "163160112665",
            "status": "SUBMISSION_REQUIRED",
            "type": "ID_DOCUMENT"
          },
          {
            "id": "133160112665",
            "status": "SUBMISSION_REQUIRED",
            "type": "PROOF_OF_ADDRESS"
          },
          {
            "id": "133160112665",
            "status": "APPROVED",
            "type": "AML"
          }
        ],
        "status": "SUBMISSION_REQUIRED"
      }
    ]
}