Synctera KYC/KYB Verifications API
Requests to initiate customer verification.
OpenAPI Specification
openapi: 3.0.3
info:
description: '<h2>Let''s build something great.</h2><p>Welcome to the official reference documentation for Synctera APIs. Our APIs are the best way to automate your company''s banking needs and are designed to be easy to understand and implement.</p><p>We''re continuously growing this library and what you see here is just the start, but if you need something specific or have a question, <a class=''text-blue-600'' href=''https://synctera.com/contact'' target=''_blank'' rel=''noreferrer''>contact us</a>.</p>
'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
title: Synctera Accounts KYC/KYB Verifications API
version: 0.20.0
servers:
- description: Production
url: https://api.synctera.com/v0
- description: Sandbox (no real world financial impact)
url: https://api-sandbox.synctera.com/v0
security:
- bearerAuth: []
tags:
- description: Requests to initiate customer verification.
name: KYC/KYB Verifications
paths:
/verifications:
get:
description: List customer verification results.
operationId: listVerifications1
parameters:
- $ref: '#/components/parameters/id_query4'
- $ref: '#/components/parameters/person_id_query'
- $ref: '#/components/parameters/business_id_query'
- $ref: '#/components/parameters/verification_type_query'
- $ref: '#/components/parameters/result_query'
- $ref: '#/components/parameters/include_history'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page_token'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/verification_list'
description: List verifications.
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal_server_error'
summary: List verifications
tags:
- KYC/KYB Verifications
x-external: true
x-status: alpha
post:
description: 'Upload evidence of an externally performed KYC/KYB. You may use your own KYC/KYB provider and upload evidence of that result to Synctera instead of using Synctera''s providers.
'
operationId: createVerification
parameters:
- $ref: '#/components/parameters/idempotency_key'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/verification'
description: Verification result to create.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/verification'
description: Created verification.
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Create a verification
tags:
- KYC/KYB Verifications
x-external: true
x-status: alpha
/verifications/{verification_id}:
get:
description: Get customer verification result.
operationId: getVerification1
parameters:
- $ref: '#/components/parameters/verification_id1'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/verification'
description: Verification representation.
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Get verification
tags:
- KYC/KYB Verifications
x-external: true
x-status: alpha
/verifications/adhoc:
description: 'Check if an individual is on any watchlists. Intended for use before a transfer payment, to ensure that the payee is not flagged.
'
summary: Check if an individual is on any watchlists
post:
operationId: verifyAdHoc
parameters:
- $ref: '#/components/parameters/idempotency_key'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/adhoc_verification_request'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/adhoc_verification_response'
description: successful check
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Check if an individual is on any watchlists
tags:
- KYC/KYB Verifications
x-external: true
/verifications/verify:
post:
description: 'Initiate identity verification and run the specified identity checks.
Verifying a personal customer requires that the following fields already be set:
* `first_name`
* `last_name`
* `dob`
* `email`
* `phone_number`
* `legal_address`
* `ssn`
Verifying a business customer requires that the following fields already be set:
* `entity_name`
* `legal_address`
'
operationId: verify
parameters:
- $ref: '#/components/parameters/idempotency_key'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/verification_request'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/verify_response'
description: Created identity request.
'400':
$ref: '#/components/responses/bad_request'
'401':
$ref: '#/components/responses/unauthorized'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
'500':
$ref: '#/components/responses/internal_server_error'
summary: Verify a customer's identity
tags:
- KYC/KYB Verifications
x-external: true
x-status: alpha
components:
parameters:
person_id_query:
description: 'Unique identifier for the person. Multiple IDs can be provided as a comma-separated list.
'
explode: false
in: query
name: person_id
required: false
schema:
example: 64438afd-fa20-4010-a573-2bbdca77cdb6,84ef251c-ab8f-47a5-bbfd-a16648f95157
items:
format: uuid
type: string
type: array
style: form
x-external: true
verification_type_query:
description: 'The type of verification run. Multiple values can be provided as a comma-separated list.
'
explode: false
in: query
name: verification_type
required: false
schema:
items:
$ref: '#/components/schemas/verification_type1'
type: array
style: form
x-external: true
result_query:
description: 'The result of the verification that was run on the party. Multiple values can be provided as a comma-separated list.
'
explode: false
in: query
name: result
required: false
schema:
items:
$ref: '#/components/schemas/verification_result'
type: array
style: form
x-external: true
page_token:
in: query
name: page_token
required: false
schema:
description: Optional pagination token to be provided to retrieve subsequent pages, returned from previous get
example: h50ffqz9q5
type: string
x-external: true
verification_id1:
description: Verification's unique identifier.
in: path
name: verification_id
required: true
schema:
example: 1b0cb707-c399-4210-9a83-0834fc6d6aa5
format: uuid
type: string
include_history:
description: If true, include old (inactive) records as well.
in: query
name: include_history
required: false
schema:
default: false
type: boolean
x-external: true
limit:
in: query
name: limit
required: false
schema:
default: 100
description: 'Maximum number of objects to return per page. If the limit is greater than 100, then it will be set to 100.
'
example: 100
minimum: 1
type: integer
x-external: true
idempotency_key:
description: An idempotency key is an arbitrary unique value generated by client to detect subsequent retries of the same request. It is recommended that a UUID or a similar random identifier be used as an idempotency key
in: header
name: Idempotency-Key
required: false
schema:
example: df122e6f-2ba8-48a5-9508-4350bba5f27e
type: string
x-external: true
business_id_query:
description: 'Unique identifier for the business. Multiple IDs can be provided as a comma-separated list.
'
explode: false
in: query
name: business_id
required: false
schema:
example: 64438afd-fa20-4010-a573-2bbdca77cdb6,84ef251c-ab8f-47a5-bbfd-a16648f95157
items:
format: uuid
type: string
type: array
style: form
x-external: true
id_query4:
description: 'Unique identifier for the resource. Multiple IDs can be provided as a comma-separated list.
'
explode: false
in: query
name: id
required: false
schema:
example: 64438afd-fa20-4010-a573-2bbdca77cdb6,84ef251c-ab8f-47a5-bbfd-a16648f95157
items:
format: uuid
type: string
type: array
style: form
x-external: true
schemas:
vendor_info:
description: 'The information provided to Synctera from the vendor. Interpretation of this object is up to the client.
'
discriminator:
mapping:
application/json: '#/components/schemas/vendor_json'
text/xml: '#/components/schemas/vendor_xml'
propertyName: content_type
oneOf:
- $ref: '#/components/schemas/vendor_json'
- $ref: '#/components/schemas/vendor_xml'
title: Vendor Info
type: object
verification_status:
description: 'The result of a KYC/KYB verification. One of the following:
* `UNVERIFIED` – verification has not been completed for this customer.
* `PENDING` – verification is in progress for this customer.
* `PROVISIONAL` – partially verified or verified with restrictions.
* `ACCEPTED` – the customer has been verified.
* `REVIEW` – verification has run and issues have been identified and require review.
* `REJECTED` – the customer was rejected and should not be allowed to take certain actions e.g., open an account.
'
enum:
- UNVERIFIED
- PENDING
- PROVISIONAL
- ACCEPTED
- REVIEW
- REJECTED
example: ACCEPTED
readOnly: true
type: string
detail:
description: An object containing information about an individual check performed.
properties:
description:
description: Human-readable description explaining the individual check.
example: Email address is correlated with the individual's name
type: string
label:
description: Human-readable grouping describing the aspect of the customer's identity examined by this check.
example: Email
type: string
result:
description: 'The result of the individual check. One of the following:
* `PASS` – the check passed contributing to a positive outcome (or accepted verification result).
* `WARN` – the results of the check were inconclusive and might require review.
* `FAIL` – the check failed and might result in a failing outcome (or rejected verification_result).
'
enum:
- PASS
- WARN
- FAIL
example: PASS
type: string
vendor_code:
description: Machine-readable description of the individual check. This field contains vendor-specific terms and may not be populated in all cases.
example: R940
type: string
readOnly: true
type: object
verify_response:
allOf:
- properties:
verification_status:
$ref: '#/components/schemas/verification_status'
verifications:
description: Array of verification results.
items:
$ref: '#/components/schemas/verification'
type: array
required:
- verification_status
- verifications
type: object
- $ref: '#/components/schemas/paginated_response'
details:
description: 'A list of individual checks done as part of the due diligence process for the verification type.
'
items:
$ref: '#/components/schemas/detail'
readOnly: true
type: array
verification_list:
allOf:
- properties:
verifications:
description: Array of verification results.
items:
$ref: '#/components/schemas/verification'
type: array
required:
- verifications
type: object
- $ref: '#/components/schemas/paginated_response'
business_id5:
description: 'Unique ID for the business. Exactly one of `business_id` or `person_id` must be set.
'
example: d6bca903-7768-436b-af68-6b46f59d6569
format: uuid
type: string
verification_type1:
description: "The verification run on the customer. One the following:\n * `IDENTITY` – verify that the information provided is associated with the identity of a real person or business.\n * `WATCHLIST` – checks watchlists for known fraud, money laundering, and other suspicious activity.\n * `RELATED_ENTITIES` – represents dependent verification checks for related parties (e.g. all beneficial owners must pass KYC for a business to pass KYB).\n * `MANUAL_REVIEW` – represents the outcome of a manual review of the verification done on a party (note: overrides the outcome of other verification types).\n"
enum:
- IDENTITY
- WATCHLIST
- RELATED_ENTITIES
- MANUAL_REVIEW
example: IDENTITY
type: string
verification_result:
description: 'The determination of this verification. One of the following:
* `PENDING` – verification is in progress for this customer.
* `PROVISIONAL` – partially verified or verified with restrictions.
* `ACCEPTED` – the customer has been verified.
* `REVIEW` – verification has run and issues have been identified and require review.
* `VENDOR_ERROR` – verification did not successfully run due to an unexpected error or failure.
* `REJECTED` – the customer was rejected and should not be allowed to take certain actions e.g., open an account.
'
enum:
- PENDING
- PROVISIONAL
- ACCEPTED
- REVIEW
- VENDOR_ERROR
- REJECTED
example: ACCEPTED
type: string
vendor_xml:
properties:
content_type:
description: Describes the content-type encoding received from the vendor
enum:
- text/xml
type: string
vendor:
example: IDOLOGY
type: string
xml:
description: Data representaion in XML
type: string
required:
- vendor
- content_type
- xml
verification:
allOf:
- required:
- verification_type
- verification_time
- result
- properties:
business_id:
$ref: '#/components/schemas/business_id5'
creation_time:
description: The date and time the resource was created.
example: '2021-06-14T11:23:41Z'
format: date-time
readOnly: true
type: string
details:
$ref: '#/components/schemas/details'
id:
description: Unique ID for this verification result.
example: 379b0b05-bb49-4812-a9c9-3efe72df042f
format: uuid
readOnly: true
type: string
last_updated_time:
description: The date and time the resource was last updated.
example: '2022-01-18T17:54:12Z'
format: date-time
readOnly: true
type: string
metadata:
$ref: '#/components/schemas/metadata'
person_id:
$ref: '#/components/schemas/person_id'
result:
$ref: '#/components/schemas/verification_result'
vendor_info:
$ref: '#/components/schemas/vendor_info'
verification_time:
description: The date and time the verification was completed.
format: date-time
type: string
verification_type:
$ref: '#/components/schemas/verification_type1'
type: object
description: Verification result.
type: object
metadata:
description: 'Optional field to store additional information about the resource. Intended to be used by the integrator to store non-sensitive data.
'
type: object
adhoc_verification_request:
description: 'Basic identifying information about the person being verified.
'
properties:
payee_id:
description: Synctera party (non-customer) who is receiving money from a customer (the payer)
format: uuid
type: string
payer_id:
description: Synctera customer who is sending money to a non-customer (the payee)
format: uuid
type: string
required:
- payer_id
- payee_id
type: object
vendor_json:
properties:
content_type:
description: Describes the content-type encoding received from the vendor
enum:
- application/json
type: string
json:
description: Data representation in JSON
type: object
vendor:
example: SOCURE
type: string
required:
- vendor
- content_type
- json
adhoc_verification_response:
properties:
id:
description: Unique ID for this verification result.
example: e1f96150-4715-424b-8f8c-ec3188628073
format: uuid
type: string
matching_watchlists:
description: 'list of watchlists that the subject of the request matched
'
items:
enum:
- US_OFAC
type: string
type: array
result:
$ref: '#/components/schemas/verification_result'
vendor_info:
$ref: '#/components/schemas/vendor_info'
required:
- id
- matching_watchlists
- result
type: object
verification_request:
allOf:
- required:
- customer_consent
- properties:
business_id:
$ref: '#/components/schemas/business_id5'
customer_consent:
description: Whether this customer has consented to be verified.
type: boolean
customer_ip_address:
description: The customer's IP address.
example: 63.239.107.232
pattern: ^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$
type: string
document_id:
description: 'The ID of the uploaded government-issued identification document provided by the Socure SDK.
'
example: 1ab2c3de-fg45-6789-a01b-23c45678defg
type: string
person_id:
$ref: '#/components/schemas/person_id'
example:
customer_consent: true
customer_ip_address: 235.2.7.2
person_id: 1bb26bcb-0e1b-4060-972d-80891332aae2
type: object
error:
properties:
detail:
description: a human-readable string explaining this particular error
example: 'missing required fields: first_name, dob'
type: string
status:
description: the HTTP status code for this response
example: 400
type: integer
title:
description: a human-readable string for this general category of error
example: Bad Request Body
type: string
type:
description: a URI that identifies this general category of error
example: https://dev.synctera.com/errors/bad-request-body
type: string
title: Standard error response (RFC 7807 problem report)
type: object
paginated_response:
properties:
next_page_token:
description: If returned, use the next_page_token to query for the next page of results. Not returned if there are no more rows.
example: d61grelm5f
type: string
title: Paginated List response
type: object
person_id:
description: 'Unique ID for the person. Exactly one of `person_id` or `business_id` must be set.
'
example: 2c0bf949-9f59-4a04-82d4-9a86e0ccec2c
format: uuid
type: string
responses:
internal_server_error:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Internal server error
not_found:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Resource not found
bad_request:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: BadRequest
forbidden:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Forbidden error
unauthorized:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/error'
description: Unauthorized
securitySchemes:
bearerAuth:
bearerFormat: api_key
scheme: bearer
type: http
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true