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