> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create external account
> Create an external account for the user.
export const RestEndpointSubjects = ({subjects = []}) => {
const subjectToIconMap = {
'client': 'browser',
'user:individual': 'user',
'user:business': 'briefcase'
};
if (subjects.length === 0) {
return null;
}
return <>
{subjects.map(subject =>
{subject}
)}
;
};
You can optionally include custom [entity metadata](../../entity-metadata) in the `metadata` field to store your own business data (e.g., cardholder name, tracking information, custom labels). If not provided during creation, you can add it later using [Set metadata](../metadata/set-metadata).
## OpenAPI
````yaml _media/specs/core-openapi.mintlify.json post /core/external-accounts
openapi: 3.1.0
info:
version: 0.1.0
title: Core 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: Authentication
description: Authentication.
- name: Countries
description: Countries.
- name: Users
description: Users.
- name: KYC
description: Individual User's KYC.
- name: KYB
description: Business User's KYB.
- name: Capabilities
description: User capabilities.
- name: Terms of service
description: User terms of service.
- name: Files
description: Files.
- name: Assets
description: Assets, networks and rails.
- name: Accounts
description: Accounts.
- name: External accounts
description: External accounts.
- name: Transactions
description: Transactions.
- name: Portfolio
description: Portfolio.
- name: Statements
description: Statements.
- name: Metadata
description: Metadata.
- name: Webhooks
description: Webhooks.
paths:
/core/external-accounts:
post:
tags:
- External accounts
summary: Create external account
description: Create an external account for the user.
operationId: core.create-external-account
requestBody:
$ref: '#/components/requestBodies/create-external-account-request-body'
responses:
'201':
$ref: '#/components/responses/create-external-account-response'
'404':
$ref: '#/components/responses/create-external-account-not-found-response'
'409':
$ref: '#/components/responses/create-external-account-conflict-response'
security:
- OAuth2:
- core.external-accounts:create
components:
requestBodies:
create-external-account-request-body:
content:
application/json:
schema:
type: object
discriminator:
propertyName: type
mapping:
card:
$ref: '#/components/schemas/create-external-account-card'
bank:
$ref: '#/components/schemas/create-external-account-bank-ach'
oneOf:
- $ref: '#/components/schemas/create-external-account-card'
title: Card
- $ref: '#/components/schemas/create-external-account-bank-ach'
title: Bank (ACH)
required:
- type
examples:
Create ACH Bank Account:
value:
type: bank
asset: USD
network: ach
label: My ACH Bank Account
address:
country: US
subdivision: US-CA
city: San Francisco
line1: 123 Main Street
line2: Apt 4B
postalCode: '94102'
routingNumber: '121000248'
accountNumber: '9876543210'
accountType: checking
Create Card:
value:
type: card
label: My Visa Card
number: '4111111111111111'
securityCode: '123'
expiryDate:
month: 12
year: 2030
metadata:
externalId: 123
responses:
create-external-account-response:
description: External account created.
content:
application/json:
schema:
type: object
properties:
externalAccount:
$ref: '#/components/schemas/external-account'
errors:
description: >-
Additional contextual errors that occurred while processing
the request.
type: object
properties:
metadata:
allOf:
- $ref: '#/components/schemas/error'
- description: Error related to metadata processing.
required:
- externalAccount
examples:
ACH Bank Account Created:
value:
externalAccount:
id: 550e8400-e29b-41d4-a716-446655440000
ownerId: 1e32fca3-23f7-40ed-bc1b-de10c790182d
type: bank
status: ok
label: My ACH Bank Account
asset: USD
network: ach
features:
- withdraw
details:
address:
country: US
subdivision: US-CA
city: San Francisco
line1: 123 Main Street
line2: Apt 4B
postalCode: '94102'
routingNumber: '121000248'
accountNumber: '9876543210'
accountType: checking
secondaryNetworks:
withdraw:
- fednow
createdAt: '2024-06-01T00:00:00.000Z'
updatedAt: '2024-07-15T00:00:00.000Z'
Card Created:
value:
externalAccount:
id: aa6e6efa-8d73-497c-8278-0347f459bd68
ownerId: 1e32fca3-23f7-40ed-bc1b-de10c790182d
type: card
status: processing
label: My Visa Card
asset: GBP
network: visa
features: []
details:
last4Digits: '1519'
expiryDate:
month: 12
year: 2030
octSupport: unknown
createdAt: '2024-06-01T00:00:00.000Z'
updatedAt: '2024-07-15T00:00:00.000Z'
Card Created With Metadata Error:
value:
externalAccount:
id: aa6e6efa-8d73-497c-8278-0347f459bd68
ownerId: 1e32fca3-23f7-40ed-bc1b-de10c790182d
type: card
status: processing
label: My Visa Card
asset: GBP
network: visa
features: []
details:
last4Digits: '1519'
expiryDate:
month: 12
year: 2030
octSupport: unknown
createdAt: '2024-06-01T00:00:00.000Z'
updatedAt: '2024-07-15T00:00:00.000Z'
errors:
metadata:
code: content_too_large
message: >-
The entity metadata size is greater than maximum size
limit
details:
threshold:
unit: characters
limit: 1024
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-external-account-not-found-response:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Rail Not Found:
value:
code: entity_not_found
message: >-
A rail for the specified type, asset and network cannot be
found
details:
entity: rail
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-external-account-conflict-response:
description: Business logic error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Bank Account Already Registered:
value:
code: duplicate
message: The bank account is already registered
details:
context: body
property: accountNumber
Bank Routing Number Invalid:
value:
code: number_invalid
message: The routing number is invalid
details:
context: body
property: routingNumber
Bank Address Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: address.country
Bank Address Subdivision Not Supported:
value:
code: subdivision_not_supported
message: The subdivision is not supported
details:
context: body
property: address.subdivision
Bank Address Postal Code Invalid:
value:
code: postal_code_invalid
message: The postal code is invalid
details:
context: body
property: address.postalCode
Card Already Registered:
value:
code: duplicate
message: The card is already registered
details:
context: body
property: number
Card Number Invalid:
value:
code: number_invalid
message: The card number is invalid
details:
context: body
property: number
Card Expiry Date Invalid:
value:
code: date_invalid
message: The date must be at least now
details:
context: body
property: expiryDate
rule: difference-less-than-or-equal-to-threshold
threshold:
limit: 0
unit: milliseconds
Card Type Not Allowed:
value:
code: card_type_not_allowed
message: The card type is not allowed
details:
type: credit
Card Issuer Country Mismatch:
value:
code: operation_not_allowed
message: >-
The card issuer country does not match the user country of
residence
details:
reasons:
- card-issuer-country-mismatch
Card Max Active Limit Exceeded:
value:
code: user_capability_failure
message: The user has capability constraints
details:
capability:
code: cards
requirements:
- user-must-delete-card
restrictions: []
Card Max Limit Exceeded:
value:
code: user_capability_failure
message: The user has capability constraints
details:
capability:
code: cards
requirements: []
restrictions:
- user-unique-card-limit-reached
Card Declined:
value:
code: operation_not_allowed
message: The card was declined
details:
reasons:
- card-declined
Card Permanently Declined:
value:
code: operation_not_allowed
message: The card was permanently declined
details:
reasons:
- card-permanently-declined
User Capability Failure:
value:
code: user_capability_failure
message: The user has capability constraints
details:
capability:
code: cards
requirements:
- user-must-submit-identity
restrictions: []
Organization Not Configured:
value:
code: operation_not_allowed
message: >-
External account type 'card' 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
schemas:
create-external-account-card:
type: object
properties:
type:
type: string
description: The type of the external account.
enum:
- card
label:
$ref: '#/components/schemas/external-account-label-for-request'
number:
type: string
description: The number of the card.
pattern: ^[0-9]{12,19}$
securityCode:
type: string
description: The security code of the card.
pattern: ^[0-9]{3,3}$
expiryDate:
type: object
properties:
month:
type: integer
description: The expiry month of the card.
minimum: 1
maximum: 12
year:
type: integer
description: The expiry year of the card.
minimum: 2000
required:
- month
- year
metadata:
$ref: '#/components/schemas/metadata'
description: Additional data for the external account.
required:
- type
- label
- number
- securityCode
- expiryDate
create-external-account-bank-ach:
type: object
properties:
type:
type: string
description: The type of the external account.
enum:
- bank
asset:
description: The asset in which the external account is denominated.
type: string
enum:
- USD
network:
type: string
description: The default network of the external account.
enum:
- ach
label:
$ref: '#/components/schemas/external-account-label-for-request'
address:
allOf:
- description: The beneficiary address.
- $ref: '#/components/schemas/address-for-request'
- type: object
required:
- country
- subdivision
- city
- line1
- postalCode
routingNumber:
description: The routing number of the bank account (ABA).
type: string
pattern: ^[0-9]{9}$
accountNumber:
description: The account number of the bank account.
type: string
pattern: ^(?!0+$)[0-9]{4,17}$
accountType:
description: The type of the bank account.
type: string
enum:
- checking
- savings
metadata:
$ref: '#/components/schemas/metadata'
description: Additional data for the external account.
required:
- type
- asset
- network
- label
- address
- routingNumber
- accountNumber
- accountType
external-account:
type: object
properties:
id:
description: The unique identifier of the external account.
type: string
format: uuid
ownerId:
description: The unique identifier of the user that owns the account.
type: string
format: uuid
type:
description: The type of the external account.
type: string
enum:
- card
- bank
- apm
status:
description: The status of the external account.
type: string
enum:
- processing
- ok
- expired
- failed
- restricted
- blocked
statusDetails:
description: The details of the status of the external account.
type: object
properties:
reason:
$ref: '#/components/schemas/external-account-status-reason'
required:
- reason
label:
description: The label of the external account.
type: string
asset:
description: The asset in which the external account is denominated.
type: string
network:
description: The network that the external account corresponds to.
type: string
features:
description: The features of the external account.
type: array
items:
type: string
enum:
- withdraw
- deposit
details:
description: The details of the external account based on the type and network.
oneOf:
- $ref: '#/components/schemas/external-account-details-card'
title: Card
- $ref: '#/components/schemas/external-account-details-bank-ach'
title: Bank (ACH)
- $ref: '#/components/schemas/external-account-details-bank-fps'
title: Bank (FPS)
- $ref: '#/components/schemas/external-account-details-bank-sepa'
title: Bank (SEPA)
- $ref: '#/components/schemas/external-account-details-apm'
title: Alternative payment method
createdAt:
description: The time at which the external account was created.
type: string
format: date-time
updatedAt:
description: The last time at which the external account was updated.
type: string
format: date-time
required:
- id
- ownerId
- type
- status
- label
- asset
- features
- details
- createdAt
- updatedAt
error:
description: The error information.
allOf:
- $ref: '#/components/schemas/feedback'
external-account-label-for-request:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- type: string
description: The label of the external account.
maxLength: 140
metadata:
type: object
additionalProperties: true
minProperties: 1
address-for-request:
description: The address information.
type: object
properties:
country:
allOf:
- $ref: '#/components/schemas/country-code-for-request'
- description: The country of the address.
subdivision:
allOf:
- $ref: '#/components/schemas/subdivision-code-for-request'
- description: The subdivision of the address.
city:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The city of the address.
type: string
maxLength: 100
line1:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The first line of the address.
type: string
maxLength: 150
line2:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The second line of the address.
type: string
maxLength: 100
postalCode:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The postal code of the address.
type: string
maxLength: 20
external-account-status-reason:
description: The reason why the external account is in its current status.
type: string
enum:
- card-data-invalid
- card-declined-by-bank
- card-expired
- card-permanently-declined-by-bank
- card-unauthorized
- card-unsupported
- bank-account-holder-name-mismatch
- velocity
- under-review
- unspecified-error
external-account-details-card:
type: object
properties:
type:
description: The type of the card, available if card was recognized.
type: string
enum:
- credit
- debit
last4Digits:
description: The last 4 digits of the card number.
type: string
pattern: ^[0-9]{4}$
expiryDate:
description: The expiry date of the card.
type: object
properties:
month:
type: integer
description: The expiry month of the card.
year:
type: integer
description: The expiry year of the card.
required:
- month
- year
octSupport:
description: The support for Open Credit Transfer (withdrawals) for the card.
type: string
enum:
- unknown
- supported
- unsupported
required:
- last4Digits
- expiryDate
- octSupport
external-account-details-bank-ach:
type: object
properties:
address:
$ref: '#/components/schemas/address'
routingNumber:
description: The routing number of the bank account (ABA).
type: string
accountNumber:
description: The account number of the bank account.
type: string
accountType:
description: The type of the bank account.
type: string
secondaryNetworks:
description: >-
The secondary networks that the external account can be used with,
grouped by operation.
type: object
properties:
deposit:
type: array
items:
type: string
withdraw:
type: array
items:
type: string
required:
- address
- routingNumber
- accountNumber
- accountType
external-account-details-bank-fps:
type: object
properties:
accountNumber:
description: The account number of the bank account.
type: string
sortCode:
description: The sort code of the bank account.
type: string
required:
- accountNumber
- sortCode
external-account-details-bank-sepa:
type: object
properties:
bic:
description: The bank account's BIC.
type: string
iban:
description: The IBAN.
type: string
required:
- bic
- iban
external-account-details-apm:
type: object
properties:
identifier:
description: The identifier of the payment method account.
type: string
required:
- identifier
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$
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}$
address:
description: The address information.
type: object
properties:
country:
description: The country of the address.
type: string
subdivision:
description: The subdivision of the address.
type: string
city:
description: The city of the address.
type: string
line1:
description: The first line of the address.
type: string
line2:
description: The second line of the address.
type: string
postalCode:
description: The postal code of the address.
type: string
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
````