Uphold
Uphold KYC sharing API

KYC sharing.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.2.0
info:
  version: 0.1.0
  title: Topper KYC sharing API
  description: The Topper API offers a set of endpoints to enable sharing of Know Your Customer (KYC) information.
  contact:
    name: Uphold API Team
    email: developer@uphold.com
    url: https://developer.uphold.com
servers:
- url: https://api.enterprise.sandbox.uphold.com
  description: Sandbox
- url: https://api.enterprise.uphold.com
  description: Production
security:
- OAuth2: []
tags:
- name: KYC sharing
  description: KYC sharing.
paths:
  /topper/kyc-sharing/identify-user:
    post:
      operationId: topper.identify-kyc-sharing-user
      summary: Identify user
      description: Identify a user for KYC sharing.
      tags:
      - KYC sharing
      security:
      - OAuth2:
        - topper.kyc-sharing:identify-user
      x-uphold:
        security:
          OAuth2:
            subjects:
            - client
            includeClient: true
            includeClientOwner: true
      parameters:
      - $ref: '#/components/parameters/x-uphold-user-ip'
      - $ref: '#/components/parameters/x-uphold-user-agent'
      - $ref: '#/components/parameters/x-uphold-user-origin'
      - $ref: '#/components/parameters/x-uphold-user-country'
      - $ref: '#/components/parameters/x-uphold-user-subdivision'
      - $ref: '#/components/parameters/x-uphold-user-city'
      requestBody:
        $ref: '#/components/requestBodies/identify-kyc-sharing-user-request-body'
      responses:
        '200':
          $ref: '#/components/responses/identify-kyc-sharing-existing-user-response'
        '201':
          $ref: '#/components/responses/identify-kyc-sharing-new-user-response'
        '400':
          $ref: '#/components/responses/bad-request'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '409':
          $ref: '#/components/responses/identify-kyc-sharing-user-conflict-response'
        '429':
          $ref: '#/components/responses/too-many-requests'
  /topper/kyc-sharing/sessions:
    post:
      operationId: topper.create-kyc-sharing-session
      summary: Create session
      description: Create a new session for KYC sharing.
      tags:
      - KYC sharing
      security:
      - OAuth2:
        - topper.kyc-sharing:create-session
      x-uphold:
        security:
          OAuth2:
            subjects:
            - client
            includeClient: true
            includeClientOwner: true
      parameters:
      - $ref: '#/components/parameters/x-uphold-user-ip'
      - $ref: '#/components/parameters/x-uphold-user-agent'
      - $ref: '#/components/parameters/x-uphold-user-origin'
      - $ref: '#/components/parameters/x-uphold-user-country'
      - $ref: '#/components/parameters/x-uphold-user-subdivision'
      - $ref: '#/components/parameters/x-uphold-user-city'
      requestBody:
        $ref: '#/components/requestBodies/create-kyc-sharing-session-request-body'
      responses:
        '200':
          $ref: '#/components/responses/create-kyc-sharing-session-completed-response'
        '201':
          $ref: '#/components/responses/create-kyc-sharing-session-created-response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/create-kyc-sharing-session-not-found-response'
        '409':
          $ref: '#/components/responses/create-kyc-sharing-session-conflict-response'
        '429':
          $ref: '#/components/responses/too-many-requests'
components:
  responses:
    forbidden:
      description: Forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Token Insufficient Scopes:
              value:
                code: token_insufficient_scopes
                message: Authorization failed due to insufficient scopes
                details:
                  security:
                  - scheme: OAuth
                    schemeScopes:
                    - required:scope_1
                    - required:scope_2
                    tokenScopes:
                    - token:scope
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    too-many-requests:
      description: Too Many Requests.
      headers:
        Retry-After:
          description: The number of seconds to wait before making a new request.
          schema:
            type: integer
            format: int32
          examples:
            Retry After:
              value: 60
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Too Many Requests:
              value:
                code: too_many_requests
                message: Try again later
    bad-request:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Invalid Request:
              value:
                code: request_invalid
                message: The request has missing or invalid parameters
                details:
                  context: <context>
                  violations:
                  - property: <property>
                    rule: required
                  - property: <property>
                    rule: type
                    ruleParams:
                      type: string
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    identify-kyc-sharing-existing-user-response:
      description: User identified.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/kyc-sharing-user'
          examples:
            Existing User Retrieved:
              value:
                user:
                  id: cd21b26d-35d2-408a-9201-b8fdbef7a604
                  email: john.doe@uphold.com
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-kyc-sharing-session-conflict-response:
      description: Business logic error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Organization Not Configured:
              value:
                code: operation_not_allowed
                message: KYC Sharing is not configured for your organization
                details:
                  reasons:
                  - permission-denied
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    identify-kyc-sharing-new-user-response:
      description: User created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/kyc-sharing-user'
          examples:
            New User Retrieved:
              value:
                user:
                  id: cd21b26d-35d2-408a-9201-b8fdbef7a604
                  email: john.doe@uphold.com
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Token Expired:
              value:
                code: token_expired
                message: The access token has expired
            Token Invalid:
              value:
                code: token_invalid
                message: The access token is invalid
            Token Revoked:
              value:
                code: token_revoked
                message: The access token has been revoked
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-kyc-sharing-session-created-response:
      description: KYC Sharing session created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/kyc-sharing'
          examples:
            KYC Sharing Session Created:
              value:
                kycSharing:
                  processes:
                  - address
                  - profile
                  - phone
                  userToken:
                    access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjbGllbnRfaWQiLCJvcmciOiIxOTRkNjJiYS1mNTg1LTQwZmYtODNkNy05Y2I5OWIxYzc3YzAiLCJzY29wZSI6InVzZXJzIGt5YyIsImlhdCI6MTcyMjUzMzA4NiwiZXhwIjoxNzIyNTMzNjg2fQ.yDFu9WgkEmvucg_38xS1qHEMq2Ku7SsMzHg8A39U2CM
                    expires_in: 600
                    token_type: Bearer
                    scope: core.kyc.address:update core.kyc.profile:update core.kyc.phone:update
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    identify-kyc-sharing-user-conflict-response:
      description: Business logic error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Country Not Supported:
              value:
                code: country_not_supported
                message: The country is not supported
                details:
                  context: body
                  property: country
            Email Incorrect or Disallowed:
              value:
                code: email_incorrect_or_disallowed
                message: The email is incorrect or disallowed
            Organization Not Configured:
              value:
                code: operation_not_allowed
                message: KYC Sharing is not configured for your organization
                details:
                  reasons:
                  - permission-denied
            Missing User Context:
              value:
                code: operation_not_allowed
                message: Request not allowed due to missing user context
                details:
                  reasons:
                  - missing-user-ip-header
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-kyc-sharing-session-completed-response:
      description: KYC sharing already completed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/kyc-sharing'
          examples:
            KYC Sharing Already Completed:
              value:
                kycSharing:
                  processes: []
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
    create-kyc-sharing-session-not-found-response:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            User Not Found:
              value:
                code: entity_not_found
                message: The user cannot be found
                details:
                  entity: user
      headers:
        x-uphold-request-id:
          description: A unique identifier for the request that can be shared with Uphold for troubleshooting purposes.
          required: true
          schema:
            type: string
            format: uuid
          examples:
            Request ID:
              value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
  schemas:
    kyc-sharing:
      type: object
      properties:
        kycSharing:
          description: The KYC sharing session.
          type: object
          properties:
            processes:
              description: The missing KYC processes.
              type: array
              items:
                type: string
                enum:
                - profile
                - address
                - email
                - phone
                - identity
            userToken:
              allOf:
              - description: The user access token to update the missing KYC processes.
              - $ref: '#/components/schemas/oauth2-token'
          required:
          - processes
      required:
      - kycSharing
    oauth2-token:
      type: object
      properties:
        access_token:
          type: string
          description: The access token string issued.
        refresh_token:
          type: string
          description: The refresh token string issued (only applicable to certain grant types).
        expires_in:
          type: integer
          description: The number of seconds until the token expires.
        scope:
          description: The list of scopes, delimited with spaces.
          type: string
        token_type:
          type: string
          enum:
          - Bearer
      required:
      - access_token
      - token_type
      - expires_in
    feedback:
      description: A feedback message with a code and human-readable description.
      type: object
      properties:
        code:
          description: A short string with a brief explanation about the code reported.
          type: string
        message:
          description: A human-readable message providing more details.
          type: string
        details:
          description: Additional information about the feedback reported.
          type: object
          additionalProperties: true
      required:
      - code
      - message
    string-no-edge-spaces:
      type: string
      pattern: ^\S.*\S$|^\S$
    error:
      description: The error information.
      allOf:
      - $ref: '#/components/schemas/feedback'
    subdivision-code-for-request:
      type: string
      pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$
    country-code-for-request:
      type: string
      pattern: ^[A-Z]{2}$
    kyc-sharing-user:
      type: object
      properties:
        user:
          type: object
          properties:
            id:
              description: The id of the user.
              type: string
              format: uuid
            email:
              description: The email address of the user.
              type: string
              format: email
          required:
          - id
          - email
      required:
      - user
  parameters:
    x-uphold-user-country:
      name: X-Uphold-User-Country
      description: Contains the code of the country of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/country-code-for-request'
      examples:
        User Country:
          value: US
    x-uphold-user-agent:
      name: X-Uphold-User-Agent
      description: Contains the user agent of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        User Agent:
          value: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36
    x-uphold-user-city:
      name: X-Uphold-User-City
      description: Contains the name of the city of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        User City:
          value: San Francisco
    x-uphold-user-ip:
      name: X-Uphold-User-Ip
      description: Contains the IP of the end user that is requesting the operation.
      in: header
      schema:
        oneOf:
        - title: IPv4
          type: string
          format: ipv4
        - title: IPv6
          type: string
          format: ipv6
      examples:
        User Ip:
          value: 47.174.97.164
    x-uphold-user-origin:
      name: X-Uphold-User-Origin
      description: Contains the origin of the request made by the end user.
      in: header
      schema:
        $ref: '#/components/schemas/string-no-edge-spaces'
      examples:
        Origin:
          value: https://uphold.com
    x-uphold-user-subdivision:
      name: X-Uphold-User-Subdivision
      description: Contains the code of the subdivision of the end user that is requesting the operation.
      in: header
      schema:
        $ref: '#/components/schemas/subdivision-code-for-request'
      examples:
        User Subdivision:
          value: US-CA
  requestBodies:
    create-kyc-sharing-session-request-body:
      content:
        application/json:
          schema:
            type: object
            properties:
              userId:
                description: The user ID to create the KYC sharing session for.
                type: string
                format: uuid
            required:
            - userId
          examples:
            Create KYC Sharing Session:
              value:
                userId: cd21b26d-35d2-408a-9201-b8fdbef7a604
    identify-kyc-sharing-user-request-body:
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                description: The email address.
                type: string
                format: email
                maxLength: 255
              country:
                allOf:
                - $ref: '#/components/schemas/country-code-for-request'
                - description: The country of residency.
            required:
            - email
            - country
          examples:
            Identify User:
              value:
                email: john.doe@uphold.com
                country: GB
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /core/oauth2/token
          scopes:
            topper.kyc-sharing:identify-user: Grants access to identify a user for KYC sharing.
            topper.kyc-sharing:create-session: Grants access to create a KYC sharing session.
Uphold KYC sharing API

Documentation

Specifications

Other Resources

OpenAPI Specification
