{ "openapi": "3.1.0", "info": { "version": "0.1.0", "title": "Topper 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": { "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." } } } } }, "parameters": { "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-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-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-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-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" } } }, "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" } } } }, "schemas": { "string-no-edge-spaces": { "type": "string", "pattern": "^\\S.*\\S$|^\\S$" }, "country-code-for-request": { "type": "string", "pattern": "^[A-Z]{2}$" }, "subdivision-code-for-request": { "type": "string", "pattern": "^[A-Z]{2}-[A-Z0-9]{1,3}$" }, "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" ] }, "error": { "description": "The error information.", "type": "object", "properties": { "code": { "description": "A short string with a brief explanation about the error code reported.", "type": "string" }, "message": { "description": "A human-readable message providing more details about the error.", "type": "string" }, "details": { "description": "Additional information about the error reported.", "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] }, "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" ] }, "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" ] } }, "requestBodies": { "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" } } } } } }, "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" } } } } } } }, "responses": { "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" } } } } }, "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" } } } } }, "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": "", "violations": [ { "property": "", "rule": "required" }, { "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" } } } } }, "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" } } } } }, "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" } } } } }, "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" } } } } }, "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" } } } } } }, "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-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" } } } } }, "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" } } } } }, "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" } } } } } } } }