# Customer Identification (KYC)

All endpoints related to customer identifications (KYC).

Version: 1.0

## Servers

Sandbox
```
https://api.solaris-sandbox.de
```

Production
```
https://api.solarisbank.de
```

## Download OpenAPI description

[Customer Identification (KYC)](https://docs.solarisgroup.com/_spec/api-reference/identity/identifications.yaml)

## Person identifications

### (Bankident only) Check identification eligibility

 - [POST /v1/persons/{person_id}/identification_eligibility_checks](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_eligibility_checks/post.md): Validates whether the person specified in the request URL is eligible to complete a given identification method.

### Create an identification

 - [POST /v1/persons/{person_id}/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications/post.md): Creates an identification for the person specified in the request URL. Note that this endpoint does  send a request to the identification provider to start the identification process.

### Index identifications for a person

 - [GET /v1/persons/{person_id}/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications/get.md): Returns all identifications for the person specified in the request URL.

### List supported documents for a person identification

 - [GET /v1/persons/{person_id}/identifications/{id}/supported_documents](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1supported_documents/get.md): Returns an array of document types that a customer may use to identify themselves along with a list of allowed issuing countries. The  are provided as ISO country codes (ISO-3166-1 alpha 2). If the customer does not provide a supported document type in the identification process, then their identification will eventually fail.

### List supported documents from Fourthline for a person identification

 - [GET /v1/persons/{person_id}/identifications/{id}/supported_documents_from_fourthline](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1supported_documents_from_fourthline/get.md): Returns an array of document types as returned from Fourthline that a customer may use to identify themselves along with a list of allowed issuing countries. The  is provided as ISO country code (ISO-3166-1 alpha 2). If the customer does not provide a supported document type in the identification process, then their identification will eventually fail.

### Request an identification

 - [PATCH /v1/persons/{person_id}/identifications/{id}/request](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1request/patch.md): This endpoint requests Solaris to begin the process for the person identification specified in the URL. The status of the identification will change to .  Once the identification process finishes, you will receive a notification from the  webhook and the status will change to  or  depending on the outcome.

### Retrieve a person identification

 - [GET /v1/persons/{person_id}/identifications/{id}](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D/get.md): Returns a completed person identification (i.e., the person identification process was successful). If you use the  filter, this method will also return the documents submitted by the customer during the identification process. 

### Index all person identifications

 - [GET /v1/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1identifications/get.md): Returns all identifications for all of your customers.

### Start e-signing authorization process

 - [PATCH /v1/persons/{person_id}/identifications/{id}/authorize](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1authorize/patch.md): This method begins the authorization process for a person identification via BankIdent. When called, it triggers a Swisscom iframe and it also prompts Swisscom to send an SMS OTP to the customer. Call this endpoint when an identification reaches the  status.

### Confirm QES e-signing

 - [PATCH /v1/persons/{person_id}/identifications/{id}/confirm](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1confirm/patch.md): Use this endpoint to send the SMS OTP from the customer to Swisscom to confirm the e-signing for a person identification via BankIdent. Call this endpoint when the person identification reaches the status .

### (Bankident only) Index person bank identification attempts

 - [GET /v1/persons/{person_id}/bank_identification_attempts](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1bank_identification_attempts/get.md): Returns all bank identifications attempts for the person specified in the request URL.

### (IDnow only) List the IDnow attempts of a person identification

 - [GET /v1/persons/{person_id}/identifications/{id}/idnow_attempts](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1idnow_attempts/get.md): Returns a list of IDnow attempts within a person identification. Each returned attempt includes the result, the reason (if the attempt was aborted), and the payload from the webhook related to that attempt.

### (IDnow only) Get legitimation data

 - [GET /v1/persons/{person_id}/identifications/{id}/legitimation_data](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1legitimation_data/get.md): Returns information about the document that was used for legitimating an identification (e.g., passport, national ID).

### Update legitimation data

 - [PATCH /v1/persons/{person_id}/identifications/{id}/legitimation_data](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1legitimation_data/patch.md): Update the legitimation data of an identification

### (Fourthline only) Upload .zip file with required identification documents

 - [POST /v1/persons/{person_id}/identifications/{id}/zip](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1zip/post.md): Uploads a .zip file to the person identification specified in the request URL (if the identification method requires it). The identification must have already been requested. This method is only relevant for identifications using 

### (PostIdent only) Retrieve PostIdent identification PDF

 - [GET /v1/persons/{person_id}/identifications/{id}/pdf](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1pdf/get.md): Returns the PDF file generated from a PostIdent identification. The identification must have already been requested.

### (AutoIdent only) Create identification that allows for a mobile number change

 - [POST /v1/persons/{person_id}/identifications/for_mobile_change](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1for_mobile_change/post.md): This endpoint creates a new identification for the customer specified in the request URL and returns the . Use this endpoint if the customer has lost access to their existing mobile phone number.  After calling this endpoint, supply the returned  in the URL of the  method.

### (Manual KYC) Set identification to successful

 - [PATCH /v1/persons/{person_id}/identifications/{id}/mark_as_successful](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1mark_as_successful/patch.md): This endpoint sets the  of an identification to . Use this endpoint if you are implementing the manual KYC flow in your solution.

### Set identification to failed

 - [PATCH /v1/persons/{person_id}/identifications/{id}/mark_as_failed](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1mark_as_failed/patch.md): This endpoint sets the  of an identification to . Use this endpoint if the identification is still is in pending status and you want to fail it with a reason.

### (IDnow only) Request person identification with robot testing

 - [PATCH /v1/persons/{person_id}/identifications/{id}/request_with_robot](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1request_with_robot/patch.md): This endpoint requests an identification for the person specified in the URL. You can pass a custom value to the testing robot using the parameter .

### Retrieve person identification account snapshot

 - [GET /v1/persons/{person_id}/identifications/{id}/account_snapshot](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1account_snapshot/get.md): Returns an account snapshot that was added to a person identification.

### (Fourthline only) Whitelist a person identification

 - [POST /v1/persons/{person_id}/identifications/{id}/whitelist](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1whitelist/post.md): This endpoint whitelists a person identification to enable the customer with the  specified in the request URL to identify again for one of your services using Fourthline.  You can only use this endpoint if a person has been previously identified successfully for one of your services using Fourthline and there's a need to identify again. However, you cannot use this endpoint to whitelist a failed identification.

### (Sandbox only) Update Fourthline identification status

 - [POST /v1/persons/{person_id}/identifications/{id}/identify_with_status](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1identify_with_status/post.md): Testing endpoint that updates the status of a Fourthline identification. See the Fourthline guide for a full list of test values.

### (Sandbox only) Assign outcome of a Fourthline identification

 - [POST /v1/persons/{person_id}/identifications/{id}/register_verification_outcome](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1register_verification_outcome/post.md): Testing endpoint to set the outcome of a Fourthline identification once it reaches a specified status. This endpoint forwards the received payload to Fourthline's "Register a Verification Outcome" endpoint. For a full description and specification of the request parameters see Fourthline's online documentation.

### (BankPlus only) Retrieve the identification account for a person identification

 - [GET /v1/persons/{person_id}/identifications/{id}/identification/identification_account](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1identification~1identification_account/get.md): Returns the account details for a bank_plus identification.

### (Sanbox only) Simulate outcome for BankPlusIdent

 - [PATCH /v1/persons/{person_id}/identifications/{id}/simulate_outcome](https://docs.solarisgroup.com/api-reference/identity/identifications/person-identifications/paths/~1v1~1persons~1%7Bperson_id%7D~1identifications~1%7Bid%7D~1simulate_outcome/patch.md): This endpoint allows you to easily test different scenarios while integrating BankPlusIdent, such as pre_successful, failed, aborted, or canceled statuses. It requires the identification to be in a pending/aborted/canceled status to simulate the desired scenario.

## Device Monitoring

### Create user consent for device monitoring

 - [POST /v1/persons/{person_id}/device_consents](https://docs.solarisgroup.com/api-reference/identity/identifications/device-monitoring/paths/~1v1~1persons~1%7Bperson_id%7D~1device_consents/post.md): Records consent from the given person (specified in the request URL) to collect device fingerprints on their registered device. Each consent is tied to a specific device.

### Update user consent for device monitoring

 - [PATCH /v1/persons/{person_id}/device_consents/{device_consent_id}](https://docs.solarisgroup.com/api-reference/identity/identifications/device-monitoring/paths/~1v1~1persons~1%7Bperson_id%7D~1device_consents~1%7Bdevice_consent_id%7D/patch.md): Records change of consent from the given person (specified in the request URL) to collect device fingerprints on their registered device. Each consent is tied to a specific device.

### Create user activity for device monitoring

 - [POST /v1/persons/{person_id}/device_activities](https://docs.solarisgroup.com/api-reference/identity/identifications/device-monitoring/paths/~1v1~1persons~1%7Bperson_id%7D~1device_activities/post.md): Records activity from the given person (specified in the request URL).

## Identification sessions

### Create an identification session

 - [POST /v1/persons/{person_id}/identification_sessions](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions/post.md): -> "Creates an identification session for the person specified in the request URL based on the identification method(s) supplied in the request. Note that if the customer is not eligible for one of the identification methods, then this endpoint will return an error. Use the eligibility checking endpoint to verify this beforehand:" + 

### Get an identification session

 - [GET /v1/persons/{person_id}/identification_sessions/{identification_session_id}](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D/get.md): Returns a specific identification session for the person specified in the request URL.

### Get the configuration of an identification session

 - [GET /v1/persons/{person_id}/identification_sessions/{identification_session_id}/configuration](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D~1configuration/get.md): Returns the configuration data for a specific person identification session.

### Create an identification within an identification session

 - [POST /v1/persons/{person_id}/identification_sessions/{identification_session_id}/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D~1identifications/post.md): Creates a person identification within an existing person identification session.

### Retrieve a single identification within an identification session

 - [GET /v1/persons/{person_id}/identification_sessions/{identification_session_id}/identifications/{id}](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D~1identifications~1%7Bid%7D/get.md): Returns the details of a person's identification. In the request URL, you must specify the identification session within which the identification was created.

### (Sandbox only) Simulate a bank identification until the authorization stage

 - [POST /v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_until_authorization](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D~1simulate_bank_until_authorization/post.md): Simulates a bank identification for the given person until the authorization stage.

### (Sandbox only) Simulate bank identification until the identification_data_required stage

 - [POST /v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_id_until_identification_data_required](https://docs.solarisgroup.com/api-reference/identity/identifications/identification-sessions/paths/~1v1~1persons~1%7Bperson_id%7D~1identification_sessions~1%7Bidentification_session_id%7D~1simulate_bank_id_until_identification_data_required/post.md): Simulates the bank identification process for the given person until the identification reaches the status .

## Person signings

### (IDnow only) Index person signings

 - [GET /v1/persons/{person_id}/signings](https://docs.solarisgroup.com/api-reference/identity/identifications/person-signings/paths/~1v1~1persons~1%7Bperson_id%7D~1signings/get.md): Returns all of the IDnow signature packages for the person specified in the request URL.

### Upload documents for the e-signature process

 - [POST /v1/persons/{person_id}/signings](https://docs.solarisgroup.com/api-reference/identity/identifications/person-signings/paths/~1v1~1persons~1%7Bperson_id%7D~1signings/post.md): Uploads documents that are required for the e-signature process in an IDnow identification. You must specify the position of the signature in the document and the type of document in the request. The options for document type are  (for contracts) and  (for SDD mandates).

### List the IDnow attempts of the IDnow identification used for a signing

 - [GET /v1/persons/{person_id}/signings/{signing_id}/idnow_attempts](https://docs.solarisgroup.com/api-reference/identity/identifications/person-signings/paths/~1v1~1persons~1%7Bperson_id%7D~1signings~1%7Bsigning_id%7D~1idnow_attempts/get.md): Returns a list of IDnow attempts within a person signing. Each returned attempt includes the result, the reason (if the attempt was aborted), and the payload from the webhook related to that attempt.

### (IDnow only) Retrieve a signing

 - [GET /v1/persons/{person_id}/signings/{signing_id}](https://docs.solarisgroup.com/api-reference/identity/identifications/person-signings/paths/~1v1~1persons~1%7Bperson_id%7D~1signings~1%7Bsigning_id%7D/get.md): Returns an IDnow e-signature package. Use this endpoint to check the status of a signing. The response includes an array of  that the customer signed. The  property of signed contracts will contain the value .

## IDnow

### Test the signing process using a robot

 - [GET /idnow/sign_with_robot](https://docs.solarisgroup.com/api-reference/identity/identifications/idnow/paths/~1idnow~1sign_with_robot/get.md): This endpoint runs through a test of the signing process using a robot. Please refer to the identification of a person with first name or last name using .

### Test the identification process using a robot

 - [GET /idnow/identify_with_robot](https://docs.solarisgroup.com/api-reference/identity/identifications/idnow/paths/~1idnow~1identify_with_robot/get.md): This endpoint runs through a test of the person identification process using a robot. Please refer to the identification of a person with first name or last name using .

## Business identifications

### Create a business identification

 - [POST /v1/businesses/{business_id}/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications/post.md): Creates the business identification resource (BKYC) for a business, which automatically triggers both the legal identification of the business (handled by Solaris) and the video identification of all applicable natural person(s), such as legal representative(s). 

### Index business identifications for a business

 - [GET /v1/businesses/{business_id}/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications/get.md): Retrieves all identifications for a business. You can filter the results by page number, page size, identification status, legal identification status, etc.

### Create an approval for business identification

 - [POST /v1/businesses/{business_id}/identifications/{business_identification_id}/approvals](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D~1approvals/post.md): Creates an additional final verification step to allow partners to approve or reject the business identification based on their internal compliance assessments. This is an optional endpoint for partners with this specific use case.

### Retrieve a single business identification

 - [GET /v1/businesses/{business_id}/identifications/{business_identification_id}](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D/get.md): Retrieves the details of a single business identification, including the status of the overall business identification process, video identification status and the URLs for the business's legal_representatives, and the legal identification status. You can use this endpoint to check status updates or any changes to the fields. 

### Index business identifications of a partner

 - [GET /v1/businesses/identifications](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1identifications/get.md): Returns all business identifications for all of your customers. You can add filters to your query to filter results.

### List all legal identification compliance questions

 - [GET /v1/businesses/{business_id}/identifications/{business_identification_id}/legal_identification/questions](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D~1legal_identification~1questions/get.md): Returns all the compliance questions raised by Solaris in relation to a business legal identification. The API response returns the compliance questions' IDs and texts. Each question has its own unique ID. You have to redirect these questions to your customers and collect their answers and submit them to Solaris.

### Create an answer to a compliance question

 - [POST /v1/businesses/{business_id}/identifications/{business_identification_id}/legal_identification/questions/{question_id}/answers](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D~1legal_identification~1questions~1%7Bquestion_id%7D~1answers/post.md): Creates an answer to a compliance question raised by Solaris in relation to a business legal identification. You have to add the question's unique  in the request URL. Please note that you can only create one answer to a single question per request.

### Mark legal_identification as ready for review

 - [PATCH /v1/businesses/{business_id}/identifications/{business_identification_id}/legal_identification/mark_as_ready](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D~1legal_identification~1mark_as_ready/patch.md): Updates the legal identification status from  to  and removes the  flag. Call this endpoint after collecting and submitting the required documents and/or answers to the compliance questions from your customers to Solaris. Afterward, Solaris will review the submitted information and resume the legal identification process.

### (Sandbox only) Update the legal identification status of a business identification

 - [PATCH /v1/businesses/{business_id}/identifications/{business_identification_id}/legal_identification](https://docs.solarisgroup.com/api-reference/identity/identifications/business-identifications/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1identifications~1%7Bbusiness_identification_id%7D~1legal_identification/patch.md): Updates the legal identification status of a business identification. This endpoint is only for testing and not available on production systems. You can use it to update the status of the business identification for testing purposes.

## Business screener hits

### Index business hits

 - [GET /v1/businesses/{business_id}/hits](https://docs.solarisgroup.com/api-reference/identity/identifications/business-screener-hits/paths/~1v1~1businesses~1%7Bbusiness_id%7D~1hits/get.md): Returns an array containing all screener hits for a business.