Customer Identification (KYC) (1.0)

Download OpenAPI specification:Download

All endpoints related to customer identifications (KYC).

Person identifications

Check identification eligibility

Validates whether the person specified in the request URL is eligible to complete a given identification method.

Request
Security:
path Parameters
person_id
required
string
Request Body schema: application/json

the content of the request

method
string

The identification method to check for eligibility for the given person.

Enum: "bank" "bank_id" "fourthline" "idnow" "manual" "postident"
Responses
200

Successful result of the operation

default

Unexpected error

post/v1/persons/{person_id}/identification_eligibility_checks
Request samples
application/json
{
  • "method": "idnow"
}
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

Create an identification

Creates an identification for the person specified in the request URL. Note that this endpoint does not send a request to the identification provider to start the identification process.

Request
Security:
path Parameters
person_id
required
string
Request Body schema: application/json

The content of the request.

method
string

The identification method to use for the person identification.

Enum: "bank_id" "bank_plus" "fourthline" "idnow" "manual" "postident"
language
string

(IDnow only) The customer's preferred language for the identification process.

Enum: "DE" "EN"
reference
string

A reference supplied by the identification provider.

proof_of_address_type
string

The type of document submitted by the customer as a proof of address. This field is mandatory if the customer's identification document does not include their address.

Enum: "BANK_ACCOUNT_STATEMENT" "CERTIFICATE_OF_REGISTRATION" "ELECTRICITY_BILL" "GAS_BILL" "HEATING_BILL" "INTERNET_BILL" "TELEPHONE_BILL" "WATER_BILL"
proof_of_address_issued_at
string <date>

The date when the proof of address document was issued. This field is mandatory if the customer's identification document does not include their address.

iban
string

The customer's IBAN. This field is mandatory if the identification method is bank_id or bank_plus.

Responses
200

Successful result of the operation

default

Unexpected error

post/v1/persons/{person_id}/identifications
Request samples
application/json
{
  • "method": "idnow",
  • "language": "EN",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03"
}
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

Index identifications for a person

Returns all identifications for the person specified in the request URL.

Request
Security:
path Parameters
person_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications'
Response samples
application/json
[
  • {
    }
]

List supported documents for a person identification

Returns an array of document types that a customer may use to identify themselves along with a list of allowed issuing countries. The issuing_countries 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.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/supported_documents
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/supported_documents'
Response samples
application/json
[
  • {
    }
]

List supported documents from Fourthline for a person identification

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 issuingCountry 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
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/supported_documents_from_fourthline
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/supported_documents_from_fourthline'
Response samples
application/json
[
  • {
    }
]

Request an identification

This endpoint requests Solaris to begin the process for the person identification specified in the URL. The status of the identification will change to pending. Once the identification process finishes, you will receive a notification from the IDENTIFICATION webhook and the status will change to completed or failed depending on the outcome.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: application/json

The content of the request.

secret
string

Identification secret.

Responses
200

The operation was successful.

403

You are not authorized to perform this action.

404

Model not found.

412

There are more than 19 unsuccessful identification attempts for this customer.

422

Client error.

500

Internal server error.

patch/v1/persons/{person_id}/identifications/{id}/request
Request samples
application/json
{
  • "secret": "string"
}
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "terms_and_conditions_signed_at": "string"
}

Retrieve a person identification

Returns a completed person identification (i.e., the person identification process was successful). If you use the include_documents filter, this method will also return the documents submitted by the customer during the identification process.

Request
Security:
path Parameters
person_id
required
string
id
required
string
query Parameters
include_documents
boolean
Default: true

Specifies whether this method should include the documents submitted during the identification process in the response.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}?include_documents=true'
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

Index all person identifications

Returns all identifications for all of your customers.

Request
Security:
query Parameters
page[number]
string

Page Number

page[size]
string

Determines the size of each page of results.

filter[reference]
string

Filters the returned identifications by a specific reference.

filter[id]
string

Filters the returned identifications by a specific identification ID.

filter[status]
string

Filters the returned identifications by a specific status.

filter[person_id]
string

Filters the returned identifications by a specific person ID.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

get/v1/identifications
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/identifications?page%5Bnumber%5D=string&page%5Bsize%5D=string&filter%5Breference%5D=string&filter%5Bid%5D=string&filter%5Bstatus%5D=string&filter%5Bperson_id%5D=string'
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

(BankIdent only) Start e-signing authorization process

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 authorization_required status. Note: This method has been implemented in the IdentHub SDK; you do not need to implement it on your own.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

The QES process has been triggered. The customer must confirm by entering the received SMS OTP.

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

patch/v1/persons/{person_id}/identifications/{id}/authorize
Request samples
curl -i -X PATCH \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/authorize'
Response samples
application/json
{}

(BankIdent only) Confirm QES e-signing

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 confirmation_required. Note: This method has been implemented in the IdentHub SDK; you do not need to implement it on your own.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

The customer has successfully entered the SMS OTP. The QES process is complete.

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

patch/v1/persons/{person_id}/identifications/{id}/confirm
Request samples
curl -i -X PATCH \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/confirm'
Response samples
application/json
{}

(Bankident only) Index person bank identification attempts

Returns all bank identifications attempts for the person specified in the request URL.

Request
Security:
path Parameters
person_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/bank_identification_attempts
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/bank_identification_attempts'
Response samples
application/json
[
  • {
    }
]

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

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.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/idnow_attempts
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/idnow_attempts'
Response samples
application/json
{
  • "id": "e1eeb07262b695dc0ee5d4ab9350c12dcida",
  • "result": "SUCCESS",
  • "reason": null,
  • "payload": {
    }
}

(IDnow only) Get legitimation data

Returns information about the document that was used for legitimating an identification (e.g., passport, national ID).

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/legitimation_data
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/legitimation_data'
Response samples
application/json
{
  • "legitimation_document_number": "123456789",
  • "legitimation_type": "PASSPORT",
  • "legitimation_issuer": "Stadt Heidelberg",
  • "legitimation_country": "GERMANY",
  • "legitimation_issued_at": "2015-10-15",
  • "legitimation_valid_until": "2025-10-14"
}

Update legitimation data

Update the legitimation data of an identification

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: application/json

the content of the request

legitimation_document_number
required
string

The document number of the legitimation

legitimation_type
string

Legitimation type

legitimation_issuer
string

Issuer of the legitimation

legitimation_country
string

Country that issued legitimation

legitimation_issued_at
string <date>

The date at which the legitimation was issued at

legitimation_valid_until
string <date>

The date until which the legitimation is valid

Responses
200

Successful result of the operation

default

Unexpected error

patch/v1/persons/{person_id}/identifications/{id}/legitimation_data
Request samples
application/json
{
  • "legitimation_document_number": "12345678910",
  • "legitimation_type": "PASSPORT",
  • "legitimation_issuer": "Stadt Heidelberg",
  • "legitimation_country": "GERMANY",
  • "legitimation_issued_at": "2010-01-01",
  • "legitimation_valid_until": "2020-01-01"
}
Response samples
application/json
{
  • "legitimation_document_number": "123456789",
  • "legitimation_type": "PASSPORT",
  • "legitimation_issuer": "Stadt Heidelberg",
  • "legitimation_country": "GERMANY",
  • "legitimation_issued_at": "2015-10-15",
  • "legitimation_valid_until": "2025-10-14"
}

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

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 Fourthline.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: multipart/form-data
document
required
string <binary>

The .zip file to upload.

Responses
200

Successful result of the operation.

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identifications/{id}/zip
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/zip' \
  -H 'Content-Type: multipart/form-data' \
  -F document=string
Response samples
application/json
{
  • "iban": "DE92370601930002130041",
  • "id": "d42a2dfcf32c4550bd1e1fe373bb953bsnap",
  • "location": "string",
  • "provider": "FIN_TEC_SYSTEMS",
  • "status": "available",
  • "status_description": "string",
  • "wizard_session_key": "wiz04852083740"
}

(PostIdent only) Retrieve PostIdent identification PDF

Returns the PDF file generated from a PostIdent identification. The identification must have already been requested.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/pdf
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/pdf'
Response samples
application/json
{
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "status": "400",
  • "code": "build_pagination_headers_failure",
  • "title": "Failed to build pagination headers.",
  • "details": "Cannot connect to database."
}

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

This endpoint creates a new identification for the customer specified in the request URL and returns the identification_id. Use this endpoint if the customer has lost access to their existing mobile phone number. After calling this endpoint, supply the returned identification_id in the URL of the PATCH /persons/{person_id}/identifications/{identification_id}/request method.

Request
Security:
path Parameters
person_id
required
string
Responses
201

Successful result of the operation.

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identifications/for_mobile_change
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/for_mobile_change'
Response samples
application/json
{
  • "identification_id": "string"
}

(Manual KYC) Set identification to successful

This endpoint sets the status of an identification to successful. Use this endpoint if you are implementing the manual KYC flow in your solution.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: application/json

The content of the request.

completed_at
required
string <date-time>

The date and time that the identification was completed (maximum 18 months in the past).

Responses
400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

patch/v1/persons/{person_id}/identifications/{id}/mark_as_successful
Request samples
application/json
{
  • "completed_at": "2019-08-24T14:15:22Z"
}
Response samples
application/json
{
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "status": "400",
  • "code": "build_pagination_headers_failure",
  • "title": "Failed to build pagination headers.",
  • "details": "Cannot connect to database."
}

(IDnow only) Request person identification with robot testing

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 custom5.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: application/json
custom5
string

Parameter for passing a custom testing string to the IDnow robot.

Responses
400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

patch/v1/persons/{person_id}/identifications/{id}/request_with_robot
Request samples
application/json
{
  • "custom5": "X-AUTOTEST-HAPPYPATH"
}
Response samples
application/json
{
  • "id": "a95f2aaf-4e0c-4d49-8021-8a16a884ed86",
  • "status": "400",
  • "code": "build_pagination_headers_failure",
  • "title": "Failed to build pagination headers.",
  • "details": "Cannot connect to database."
}

Retrieve person identification account snapshot

Returns an account snapshot that was added to a person identification.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Responses
200

AccountSnapshot

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identifications/{id}/account_snapshot
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identifications/{id}/account_snapshot'
Response samples
application/json
{
  • "iban": "DE92370601930002130041",
  • "id": "d42a2dfcf32c4550bd1e1fe373bb953bsnap",
  • "location": "string",
  • "provider": "FIN_TEC_SYSTEMS",
  • "status": "available",
  • "status_description": "string",
  • "wizard_session_key": "wiz04852083740"
}

(Sandbox only) Update Fourthline identification status

Testing endpoint that updates the status of a Fourthline identification. See the Fourthline guide for a full list of test values.

Request
Security:
path Parameters
person_id
required
string
id
required
string
Request Body schema: application/json

The content of the request.

provider_status_code
required
string

A Fourthline status code. See the documentation linked above for a full list of possible values.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identifications/{id}/identify_with_status
Request samples
application/json
{
  • "provider_status_code": "10"
}
Response samples
application/json
{
  • "result": "Identification {id} successfully started"
}

Identification sessions

Create an identification session

-> "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 /v1/persons/{person_id}/identification_eligibility_checks

Request
Security:
path Parameters
person_id
required
string
Request Body schema: application/json

The content of the request.

callback_url
string

The callback URL to call when the identification session is completed.

identification_methods
Array of strings

Identification methods to use to identify the customer.

Items Enum: "bank" "bank_id" "fourthline" "idnow"
Responses
201

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identification_sessions
Request samples
application/json
{
  • "callback_url": "someurl.com",
  • "identification_methods": [
    ]
}
Response samples
application/json
{}

Get an identification session

Returns a specific identification session for the person specified in the request URL.

Request
Security:
path Parameters
person_id
required
string
identification_session_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identification_sessions/{identification_session_id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identification_sessions/{identification_session_id}'
Response samples
application/json
{}

Get the configuration of an identification session

Returns the configuration data for a specific person identification session.

Request
Security:
path Parameters
person_id
required
string
identification_session_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identification_sessions/{identification_session_id}/configuration
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identification_sessions/{identification_session_id}/configuration'
Response samples
application/json
{
  • "terms_and_conditions_pre_accepted": true,
  • "fourthline_provider": "fourthline"
}

Create an identification within an identification session

Creates a person identification within an existing person identification session.

Request
Security:
path Parameters
person_id
required
string
identification_session_id
required
string
Request Body schema: application/json

The content of the request.

method
string

The identification method to use for the person identification.

Enum: "bank_id" "bank_plus" "fourthline" "idnow" "manual" "postident"
language
string

(IDnow only) The customer's preferred language for the identification process.

Enum: "DE" "EN"
reference
string

A reference supplied by the identification provider.

proof_of_address_type
string

The type of document submitted by the customer as a proof of address. This field is mandatory if the customer's identification document does not include their address.

Enum: "BANK_ACCOUNT_STATEMENT" "CERTIFICATE_OF_REGISTRATION" "ELECTRICITY_BILL" "GAS_BILL" "HEATING_BILL" "INTERNET_BILL" "TELEPHONE_BILL" "WATER_BILL"
proof_of_address_issued_at
string <date>

The date when the proof of address document was issued. This field is mandatory if the customer's identification document does not include their address.

iban
string

The customer's IBAN. This field is mandatory if the identification method is bank_id or bank_plus.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identification_sessions/{identification_session_id}/identifications
Request samples
application/json
{
  • "method": "idnow",
  • "language": "EN",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03"
}
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

Retrieve a single identification within an identification session

Returns the details of a person's identification. In the request URL, you must specify the identification session within which the identification was created.

Request
Security:
path Parameters
identification_session_id
required
string
person_id
required
string
id
required
string
query Parameters
include_documents
boolean
Default: true

Specifies whether the response should include the documents submitted during identification.

Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/identification_sessions/{identification_session_id}/identifications/{id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identification_sessions/{identification_session_id}/identifications/{id}?include_documents=true'
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

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

Simulates a bank identification for the given person until the authorization stage.

Request
Security:
path Parameters
person_id
required
string
identification_session_id
required
string
Responses
201

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_until_authorization
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_until_authorization'
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

(Sandbox only) Simulate bank identification until the identification_data_required stage

Simulates the bank identification process for the given person until the identification reaches the status identification_data_required.

Request
Security:
path Parameters
person_id
required
string
identification_session_id
required
string
Responses
201

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

post/v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_id_until_identification_data_required
Request samples
curl -i -X POST \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/identification_sessions/{identification_session_id}/simulate_bank_id_until_identification_data_required'
Response samples
application/json
{
  • "id": "9dfe2f4edaa67138be0c0c1cd3a7d849cidt",
  • "reference": "TST-ELCCJ",
  • "url": "https://go.test.idnow.de/",
  • "status": "successful",
  • "completed_at": "2021-09-14T18:18:28.000Z",
  • "method": "idnow",
  • "proof_of_address_type": "GAS_BILL",
  • "proof_of_address_issued_at": "2021-12-03",
  • "language": "EN",
  • "person_id": "992de312a545bb24a88ddbf57ae8b1ffcper",
  • "address": {
    },
  • "documents": [
    ],
  • "failure_reason": "ALREADY_IDENTIFIED_SUCCESSFULLY",
  • "iban": "DE11010101010101010100",
  • "authorization_expires_at": "string",
  • "confirmation_expires_at": "string",
  • "provider_status_code": 1000
}

Person signings

(IDnow only) Index person signings

Returns all of the IDnow signature packages for the person specified in the request URL.

Request
Security:
path Parameters
person_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/signings
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/signings'
Response samples
application/json
[
  • {
    }
]

Upload documents for the e-signature process

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 cdoc (for contracts) and ldoc (for SDD mandates).

Request
Security:
path Parameters
person_id
required
string
Request Body schema: application/json

The content of the request

method
required
string

The identification method for which the documents are being uploaded.

Enum: "idnow" "postident"
language
string

The customer's preferred language for the IDnow agent.

Enum: "DE" "EN"
Array of objects
Responses
200

Successful result of the operation

default

Unexpected error

post/v1/persons/{person_id}/signings
Request samples
application/json
{
  • "method": "idnow",
  • "language": "EN",
  • "documents": [
    ]
}
Response samples
application/json
{
  • "id": "7da925f612600ee0a2c386afe1cac4bccsig",
  • "reference": "TST-QMNBB",
  • "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/155b0818593319dd718e2ec139718973cidt/webcam",
  • "state": "successful",
  • "status": "finished",
  • "completed_at": "2020-04-08T12:53:42.000Z",
  • "method": "idnow",
  • "identification_id": "155b0818593319dd718e2ec139718973cidt",
  • "documents": [
    ]
}

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

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.

Request
Security:
path Parameters
person_id
required
string
signing_id
required
string
Responses
200

Successful result of the operation

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/signings/{signing_id}/idnow_attempts
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/signings/{signing_id}/idnow_attempts'
Response samples
application/json
{
  • "id": "e1eeb07262b695dc0ee5d4ab9350c12dcida",
  • "result": "SUCCESS",
  • "reason": null,
  • "payload": {
    }
}

(IDnow only) Retrieve a signing

Returns an IDnow e-signature package. Use this endpoint to check the status of a signing. The response includes an array of documents that the customer signed. The document_type property of signed contracts will contain the value SIGNED_CONTRACT.

Request
Security:
path Parameters
person_id
required
string
signing_id
required
string
Responses
200

Successful result of the operation.

400

An error occurred on the client side.

403

You are not authorized to perform this action.

500

Internal server error.

default

Unexpected error

get/v1/persons/{person_id}/signings/{signing_id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/persons/{person_id}/signings/{signing_id}'
Response samples
application/json
{
  • "id": "7da925f612600ee0a2c386afe1cac4bccsig",
  • "reference": "TST-QMNBB",
  • "url": "https://go.test.idnow.de/solarisbankesignsandbox/identifications/155b0818593319dd718e2ec139718973cidt/webcam",
  • "state": "successful",
  • "status": "finished",
  • "completed_at": "2020-04-08T12:53:42.000Z",
  • "method": "idnow",
  • "identification_id": "155b0818593319dd718e2ec139718973cidt",
  • "documents": [
    ]
}

IDnow

Test the signing process using a robot

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 X-AUTOTEST-your_robot_name.

Request
Security:
query Parameters
identification_id
string

The identification_id of the signing

Responses
default

Unexpected error

get/idnow/sign_with_robot
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/idnow/sign_with_robot?identification_id=string'

Endpoint to accept idnow webhook

Accepts webhook

Request
Security:
Responses
default

Unexpected error

post/idnow/webhook
Request samples
curl -i -X POST \
  https://api.solaris-sandbox.de/idnow/webhook

Test the identification process using a robot

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 X-AUTOTEST-your_robot_name.

Request
Security:
query Parameters
id
string
Responses
default

Unexpected error

get/idnow/identify_with_robot
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/idnow/identify_with_robot?id=string'

Business identifications

Create a business identification

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).

Request
Security:
path Parameters
business_id
required
string

The unique business ID, generated after completing the business onboarding process.

Request Body schema: application/json

the content of the request

method
string

The identification method. Default value is idnow.

Enum: "idnow" "itm" "import"
original_completed_at
string <date-time>

The date and time when the original identification was completed. This field is only relevant if the identification method is import.

Responses
200

Successful result of the operation

400

Invalid request

403

Forbidden

500

Generic Error

post/v1/businesses/{business_id}/identifications
Request samples
application/json
{
  • "method": "idnow"
}
Response samples
application/json
{
  • "id": "4c74c804eaea5d2a2d64ef400a27a4d3bid",
  • "method": "idnow",
  • "reference": "TST-VWKRA",
  • "status": "pending",
  • "completed_at": "2021-20-03T18:01:48.000Z",
  • "legal_representatives": [
    ],
  • "legal_identification_status": "information_required",
  • "legal_identification_reason": "string",
  • "legal_identification_missing_information": "COMPLIANCE_QUESTIONS",
  • "legal_identification_missing_information_details": "string",
  • "business_id": "880bbac68a34add190786b9c74f4c82fcbiz"
}

Index business identifications for a business

Retrieves all identifications for a business. You can filter the results by page number, page size, identification status, legal identification status, etc.

Request
Security:
path Parameters
business_id
required
string

Your unique business ID, generated after completing the business onboarding process.

Responses
200

Successful result of the operation

400

Invalid request

403

Forbidden

500

Generic Error

get/v1/businesses/{business_id}/identifications
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/businesses/{business_id}/identifications'
Response samples
application/json
{
  • "id": "4c74c804eaea5d2a2d64ef400a27a4d3bid",
  • "method": "idnow",
  • "reference": "TST-VWKRA",
  • "status": "pending",
  • "completed_at": "2021-20-03T18:01:48.000Z",
  • "legal_representatives": [
    ],
  • "legal_identification_status": "information_required",
  • "legal_identification_reason": "string",
  • "legal_identification_missing_information": "COMPLIANCE_QUESTIONS",
  • "legal_identification_missing_information_details": "string",
  • "business_id": "880bbac68a34add190786b9c74f4c82fcbiz"
}

Create an approval for business identification

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.

Request
Security:
path Parameters
business_id
required
string

The unique business ID, generated after completing the business onboarding process.

business_identification_id
required
string

The unique ID of the business identification resource.

Request Body schema: application/json

the content of the request

approved
required
boolean

The partner identification approval status.

Responses
200

Successful result of the operation

400

Invalid request

403

Forbidden

500

Generic Error

post/v1/businesses/{business_id}/identifications/{business_identification_id}/approvals
Request samples
application/json
{
  • "approved": true
}
Response samples
application/json
{
  • "business_identification_id": "4c74c804eaea5d2a2d64ef400a27a4d3bid",
  • "approved": true
}

Retrieve a single business identification

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.

Request
Security:
path Parameters
business_id
required
string

The unique business ID, generated after completing the business onboarding process.

business_identification_id
required
string

The unique ID of the business identification resource.

Responses
200

Successful result of the operation

400

Invalid request

403

Forbidden

500

Generic Error

get/v1/businesses/{business_id}/identifications/{business_identification_id}
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/businesses/{business_id}/identifications/{business_identification_id}'
Response samples
application/json
{
  • "id": "4c74c804eaea5d2a2d64ef400a27a4d3bid",
  • "method": "idnow",
  • "reference": "TST-VWKRA",
  • "status": "pending",
  • "completed_at": "2021-20-03T18:01:48.000Z",
  • "legal_representatives": [
    ],
  • "legal_identification_status": "information_required",
  • "legal_identification_reason": "string",
  • "legal_identification_missing_information": "COMPLIANCE_QUESTIONS",
  • "legal_identification_missing_information_details": "string",
  • "business_id": "880bbac68a34add190786b9c74f4c82fcbiz"
}

Index business identifications of a partner

Returns all business identifications for all of your customers. You can add filters to your query to filter results.

Request
Security:
query Parameters
page[number]
string

The number of pages to be returned.

page[size]
string

The size to apply to each page of the API response.

filter[provider]
string

Filter by identification providers.

filter[reference]
string

Filter by identification reference numbers.

filter[status]
string

Filter by the business identification status.

filter[completed_at]
string

Filter by the date and time when the business identification was completed.

filter[created_at]
string

Filter by the date and time when the business identification was created.

filter[updated_at]
string

Filter by the date and time when the business identification was last updated.

filter[legal_identification_status]
string

Filter by the business legal identification status.

Responses
200

Successful result of the operation

400

Invalid request

403

Forbidden

500

Generic Error

get/v1/businesses/identifications
Request samples
curl -i -X GET \
  'https://api.solaris-sandbox.de/v1/businesses/identifications?page%5Bnumber%5D=string&page%5Bsize%5D=string&filter%5Bprovider%5D=string&filter%5Breference%5D=string&filter%5Bstatus%5D=string&filter%5Bcompleted_at%5D=string&filter%5Bcreated_at%5D=string&filter%5Bupdated_at%5D=string&filter%5Blegal_identification_status%5D=string'
Response samples
application/json
{
  • "id": "4c74c804eaea5d2a2d64ef400a27a4d3bid",
  • "method": "idnow",
  • "reference": "TST-VWKRA",
  • "status": "pending",
  • "completed_at": "2021-20-03T18:01:48.000Z",
  • "legal_representatives": [
    ],
  • "legal_identification_status": "information_required",
  • "legal_identification_reason": "string",
  • "legal_identification_missing_information": "COMPLIANCE_QUESTIONS",
  • "legal_identification_missing_information_details": "string",
  • "business_id": "880bbac68a34add190786b9c74f4c82fcbiz"
}

List all legal identification compliance questions

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.

Request
Security:
path Parameters
business_id
required
string

The unique business ID, generated after completing the business onboarding process.