Uphold
Uphold Countries API

Countries.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.2.0
info:
  version: 0.1.0
  title: Core Countries API
  description: The Core API provides essential building blocks that empower businesses to embed financial services into their applications.
  contact:
    name: Uphold API Team
    email: developers@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: Countries
  description: Countries.
paths:
  /core/countries:
    get:
      operationId: core.list-countries
      summary: List countries
      description: List countries supported by the platform.
      tags:
      - Countries
      x-uphold:
        security:
          OAuth2:
            subjects:
            - client
            - user:business
            - user:individual
      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'
      responses:
        '200':
          $ref: '#/components/responses/list-countries-response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '429':
          $ref: '#/components/responses/too-many-requests'
  /core/countries/{country}:
    get:
      operationId: core.get-country
      summary: Get country
      description: Retrieve a country by code.
      tags:
      - Countries
      x-uphold:
        security:
          OAuth2:
            subjects:
            - client
            - user:business
            - user:individual
      parameters:
      - $ref: '#/components/parameters/country-code'
      - $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'
      responses:
        '200':
          $ref: '#/components/responses/get-country-response'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/get-country-not-found-response'
        '429':
          $ref: '#/components/responses/too-many-requests'
components:
  responses:
    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
    list-countries-response:
      description: Countries list retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              countries:
                type: array
                items:
                  $ref: '#/components/schemas/country'
            required:
            - countries
          examples:
            Countries List Retrieved:
              value:
                countries:
                - code: GB
                  name: United Kingdom
                  asset: GBP
                  restrictions: []
                  subdivisions:
                  - code: GB-BAS
                    name: Bath and North East Somerset
                    restrictions: []
                  - code: GB-LND
                    name: London, City of
                    restrictions: []
                - code: US
                  name: United States of America
                  asset: USD
                  restrictions: []
                  subdivisions:
                  - code: US-CA
                    name: California
                    restrictions: []
                  - code: US-NY
                    name: New York
                    restrictions:
                    - scope: residence
      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
    get-country-response:
      description: Country retrieved.
      content:
        application/json:
          schema:
            type: object
            properties:
              country:
                $ref: '#/components/schemas/country'
          examples:
            Country Retrieved:
              value:
                country:
                  code: GB
                  name: United Kingdom
                  asset: GBP
                  restrictions: []
                  subdivisions:
                  - code: GB-BAS
                    name: Bath and North East Somerset
                    restrictions: []
                  - code: GB-LND
                    name: London, City of
                    restrictions: []
            Restricted Country Retrieved:
              value:
                country:
                  code: VE
                  name: Venezuela
                  asset: VEF
                  restrictions:
                  - scope: citizenship
                  - scope: residence
                  - scope: phone
                  - scope: geolocation
                  subdivisions:
                  - code: VE-A
                    name: Distrito Capital
                    restrictions:
                    - scope: residence
                  - code: VE-P
                    name: Portuguesa
                    restrictions:
                    - scope: residence
            Country With Restricted Subdivisions Retrieved:
              value:
                country:
                  code: US
                  name: United States of America
                  asset: USD
                  restrictions: []
                  subdivisions:
                  - code: US-CA
                    name: California
                    restrictions: []
                  - code: US-NY
                    name: New York
                    restrictions:
                    - scope: residence
      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
    get-country-not-found-response:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Country Not Found:
              value:
                code: entity_not_found
                message: The country cannot be found
                details:
                  entity: country
      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:
    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
    country-restriction-scope:
      description: The scope of the country restriction.
      type: string
      enum:
      - citizenship
      - geolocation
      - phone
      - residence
    country:
      type: object
      properties:
        code:
          description: The unique code of the country.
          type: string
        name:
          description: The name of the country.
          type: string
        asset:
          description: The national asset of the country.
          type: string
        restrictions:
          description: The restrictions of the country.
          type: array
          items:
            type: object
            properties:
              scope:
                allOf:
                - $ref: '#/components/schemas/country-restriction-scope'
                - description: The scope of the restriction.
        subdivisions:
          description: The subdivisions of the country.
          type: array
          items:
            type: object
            properties:
              code:
                description: The unique code of the subdivision.
                type: string
              name:
                description: The name of the subdivision.
                type: string
              restrictions:
                description: The restrictions of the country.
                type: array
                items:
                  type: object
                  properties:
                    scope:
                      allOf:
                      - $ref: '#/components/schemas/subdivision-restriction-scope'
                      - description: The scope of the restriction.
            required:
            - code
            - name
            - restrictions
      required:
      - code
      - name
      - asset
      - restrictions
      - subdivisions
    subdivision-restriction-scope:
      description: The scope of the subdivision restriction.
      type: string
      enum:
      - residence
    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}$
  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
    country-code:
      name: country
      description: The unique code of the country.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/country-code-for-request'
      examples:
        United Kingdom:
          value: GB
    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
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication.
      flows:
        clientCredentials:
          tokenUrl: /core/oauth2/token
          scopes:
            core.users:act-on-behalf-of: Grants access to act on behalf of a user
            core.users:create: Grants access to create users
            core.users:read: Grants access to view users
            core.users:delete: Grants access to delete users
            core.users.metadata:read: Grants access to view user metadata
            core.users.metadata:write: Grants access to modify user metadata
            core.kyc:read: Grants access to view KYC processes
            core.kyc.profile:update: Grants access to update profile KYC process
            core.kyc.address:update: Grants access to update address KYC process
            core.kyc.email:update: Grants access to update email KYC process
            core.kyc.phone:update: Grants access to update phone KYC process
            core.kyc.identity:update: Grants access to update identity KYC process
            core.kyc.proof-of-address:update: Grants access to update proof-of-address KYC process
            core.kyc.customer-due-diligence:update: Grants access to update customer due diligence KYC process
            core.kyc.enhanced-due-diligence:update: Grants access to update enhanced due diligence KYC process
            core.kyc.crypto-risk-assessment:update: Grants access to update crypto risk assessment KYC process
            core.kyc.self-categorization-statement:update: Grants access to update self-categorization statement KYC process
            core.kyc.tax-details:update: Grants access to update tax details KYC process
            core.capabilities:read: Grants access to view user capabilities
            core.terms-of-service:read: Grants access to view terms of service
            core.terms-of-service:accept: Grants access to accept terms of service
            core.files:create: Grants access to create files
            core.files:read: Grants access to view files
            core.files.metadata:read: Grants access to view files metadata
            core.files.metadata:write: Grants access to modify files metadata
            core.accounts:create: Grants access to create accounts
            core.accounts:read: Grants access to view accounts
            core.accounts:update: Grants access to update accounts
            core.accounts:archive: Grants access to archive accounts
            core.accounts:deposit-method: Grants access to deposit method needed for depositing into accounts
            core.accounts:use-test-helpers: Grants access to test helpers of accounts
            core.accounts.metadata:read: Grants access to view accounts metadata
            core.accounts.metadata:write: Grants access to modify accounts metadata
            core.assets:use-test-helpers: Grants access to test helpers of assets
            core.external-accounts:create: Grants access to create external accounts
            core.external-accounts:read: Grants access to view external accounts
            core.external-accounts:update: Grants access to update external accounts
            core.external-accounts:delete: Grants access to delete external accounts
            core.external-accounts.metadata:read: Grants access to view external accounts metadata
            core.external-accounts.metadata:write: Grants access to modify external accounts metadata
            core.transactions:create: Grants access to commit quotes
            core.transactions:read: Grants access to view transactions
            core.transactions.metadata:read: Grants access to view transactions metadata
            core.transactions.metadata:write: Grants access to modify transactions metadata
            core.transactions.requests-for-information:read: Grants access to view transactions requests for information
            core.transactions.requests-for-information:update: Grants access to update transactions requests for information
            core.portfolio:read: Grants access to view portfolio overview, performance, and historical balance
            core.statements:read: Grants access to read statements
            core.webhooks:management-link: Grants access to create webhook management links
Uphold Countries API

Documentation

Specifications

Other Resources

OpenAPI Specification
