An example account encoded in JSON looks like this:
{
"billing": {
"name": "Abigail Davis"
},
"brand": "visa",
"currency": "USD",
"id": "0874745c-f0bf-4973-a3d9-9832aeaae087",
"label": "Savings Account",
"status": "ok",
"type": "card"
}| Property | Description |
|---|---|
| billing | The relevant billing details associated with the account. |
| brand | The brand of the card account. |
| currency | The currency in which the account is denominated. |
| id | A unique ID associated with the account. |
| label | The display name of the account as chosen by the user. |
| status | The current status of the account. Possible values are ok and failed. |
| type | The type of the account. Possible values are card and sepa. |
An example authentication method encoded in JSON looks like this:
{
"default": false,
"id": "3f8f8264-2f5e-4b2b-8333-473715ab039a",
"label": "Authenticator TOTP",
"type": "totp",
"verified": true,
"verifiedAt": "2019-02-11T14:31:48.485Z"
}| Property | Description |
|---|---|
| default | A boolean signalling whether or not the method is the default. |
| id | A unique ID associated with the account. |
| label | The display name of the authentication method. |
| type | The type of authentication method. Possible values are authy and totp. |
| verified | A boolean signalling whether or not the authentication method has been verified. |
| verifiedAt | The date and time of verification of the authentication method. |
An example card encoded in JSON looks like this:
{
"address": {
"bitcoin": "ms22VBPSahNTxHZNkYo2d4Rmw1Tgfx6ojr"
},
"available": "146.38",
"balance": "146.38",
"currency": "EUR",
"id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
"label": "EUR card",
"lastTransactionAt": "2018-08-01T09:53:51.258Z",
"normalized": [{
"available": "170.96",
"balance": "170.96",
"currency": "USD"
}],
"settings": {
"position": 2,
"protected": false,
"starred": true
}
}| Property | Description |
|---|---|
| address | A key/value pair representing the primary address for the card. |
| available | The balance available for withdrawal/usage. |
| balance | The total balance of the card, including all pending transactions. |
| currency | The currency by which the card is denominated. |
| id | A unique ID associated with the card. |
| label | The display name of the card as chosen by the user. |
| lastTransactionAt | A timestamp of the last time a transaction on this card was conducted. |
| normalized | Contains the normalized available and balance values in the currency set by the user in the settings. |
| settings | This property contains the following keys: |
starred: Indicates whether the card is starred or not. |
|
DEPRECATED position: The card's current position. |
An example currency pair encoded in JSON looks like this:
{
"ask": "6420.05",
"bid": "6419",
"currency": "USD",
"pair": "BTCUSD"
}A currency pair is the combination of two currencies, encoded as two currency codes concatenated together to represent the current status of converting the first currency into the second. For example, the currency pair "BTCUSD" represents moving from bitcoin to US dollars.
Each currency pair has four properties:
| Property | Description |
|---|---|
| ask | The current ask price, or the price we quote when selling the asset. |
| bid | The current bid price, or the price we quote when buying the asset. |
| currency | The currency that is used in the ask and bid prices. |
| pair | The currency pair AB represents moving from A to B. |
An example phone encoded in JSON looks like this:
{
"e164Masked": "+XXXXXXXXX04",
"id": "1d78aeb5-43ac-4ee8-8d28-1291b5d8355c",
"internationalMasked": "+X XXX-XXX-XX04",
"nationalMasked": "(XXX) XXX-XX04",
"primary": true,
"verified": true
}
| Property | Description |
|---|---|
| e164Masked | The masked representation of the phone number in the E.164 format. |
| id | A unique ID in the Uphold platform identifying the phone. |
| internationalMasked | The masked representation of the phone number in international format. |
| nationalMasked | The masked representation of the phone number in national format. |
| primary | A boolean indicating if this phone number is the user's primary phone number. |
| verified | A boolean indicating if this phone number has been verified. |
google-libphonenumber package.
An example transaction encoded in JSON looks like this:
{
"application": null,
"createdAt": "2018-08-01T09:53:47.020Z",
"denomination": {
"amount": "5.00",
"currency": "GBP",
"pair": "GBPUSD",
"rate": "1.31"
},
"destination": {
"CardId": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
"amount": "5.57",
"base": "5.61",
"commission": "0.04",
"currency": "EUR",
"description": "Angel Rath",
"fee": "0.00",
"isMember": true,
"node": {
"id": "bc9b3911-4bc1-4c6d-ac05-0ae87dcfc9b3",
"type": "card",
"user": {
"id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
}
},
"rate": "0.85620",
"type": "card"
},
"fees": [{
"amount": "0.04",
"currency": "EUR",
"percentage": "0.65",
"target": "destination",
"type": "exchange"
}],
"id": "2c326b15-7106-48be-a326-06f19e69746b",
"message": null,
"network": "uphold",
"normalized": [{
"amount": "6.56",
"commission": "0.05",
"currency": "USD",
"fee": "0.00",
"rate": "1.00000",
"target": "destination"
}],
"origin": {
"CardId": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
"amount": "6.56",
"base": "6.56",
"commission": "0.00",
"currency": "USD",
"description": "Angel Rath",
"fee": "0.00",
"isMember": true,
"node": {
"id": "48ce2ac5-c038-4426-b2f8-a2bdbcc93053",
"type": "card",
"user": {
"id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945"
}
},
"rate": "1.16795",
"sources": [{
"amount": "6.56",
"id": "3db4ef24-c529-421f-8e8f-eb9da1b9a582"
}],
"type": "card"
},
"params": {
"currency": "USD",
"margin": "0.65",
"pair": "EURUSD",
"progress": "1",
"rate": "1.16795",
"ttl": 18000,
"type": "transfer"
},
"priority": "normal",
"reference": null,
"status": "completed",
"type": "transfer"
}Transactions record the movement of value into, within and out of the Uphold network. Transactions have the following properties:
There are two views of a transaction: public and private. The private view of information only privy to those who were a party to the transaction. Public views suppress and hide any private or personally identifiable information in order for Uphold to protect user privacy.| Property | Description |
|---|---|
| application | The application that created the transaction. |
| createdAt | The date and time the transaction was initiated. |
| denomination | The funds to be transferred, as originally requested. See Denomination. |
| destination | The recipient of the funds. See Destination. |
| fees | The fees that were applied to the transaction. See Fees. |
| id | A unique ID on the Uphold Network associated with the transaction. |
| message | An optional note added when initiating the transaction. Expected to be human-readable prose, e.g. for providing additional information and context about the nature/purpose of the transaction. |
| network | The network of the transaction (uphold for internal transactions). |
| normalized | The transaction details in USD. See Normalized. |
| origin | The sender of the funds. See Origin. |
| params | Other parameters of this transaction. See Parameters. |
| priority | The priority of the transaction. Possible values are normal and fast. |
| reference | A reference code assigned to the transaction. Can be any string, up to 100 characters. This is not exposed to the user; a possible use case is to reference an external ID in another system. |
| status | The current status of the transaction. Possible values are pending, processing, waiting, cancelled, failed and completed. |
| type | The nature of the transaction. Possible values are deposit, transfer and withdrawal. |
The actual value being transacted is denominated in a certain currency, as expressed by the denomination field with the following properties:
| Property | Description |
|---|---|
| amount | The amount to be transacted. |
| currency | The currency for said amount. |
| pair | The currency pair representing the denominated currency and the currency at origin. |
| rate | The quoted rate for converting between the denominated currency and the currency at origin. |
denomination and origin are the same currency, the rate will be '1.00'.
The fees property contains an array of fees that were applied to the transaction.
Each object in the array contains the following properties:
| Property | Description |
|---|---|
| amount | The amount to be charged. |
| currency | The currency for said amount. |
| percentage | The percentage amount to be charged. |
| target | Can be origin or destination and determines where the fee was applied. |
| type | The type of fee. Can be one of: deposit, exchange, network or withdrawal. |
The params property associated with a transaction records additional meta data relating to the respective transaction. It contains the following properties:
| Property | Description |
|---|---|
| currency | The currency in which the total commission is expressed. |
| margin | Uphold's commission expressed in percentage. |
| pair | The currency pair associated with any exchange that took place, if any. |
| progress | In case a transaction is coming in from the outside, how many confirmations have been received. |
| rate | The exchange rate of the transaction. |
| ttl | The time this quote is good for, in milliseconds. |
| type | The type of the transaction. Possible values are deposit, transfer and withdrawal. |
The normalized property contains the normalized amount and commission values in USD:
| Property | Description |
|---|---|
| amount | The amount to be transacted. |
| commission | The total commission taken on this transaction, either at origin or at destination. |
| currency | The currency in which the amount and commission are expressed. The value is always USD. |
| fee | The normalized fee amount. |
| rate | The exchange rate for this currency pair. |
| target | Can be origin or destination and determines where the fee was applied. |
The origin has properties regarding how the transaction affects the origin of the funds:
| Property | Description |
|---|---|
| CardId | The ID of the card debited. Only visible to the user who sends the transaction. |
| amount | The amount debited, including commissions and fees. |
| base | The amount to debit, before commissions or fees. |
| commission | The commission charged by Uphold to process the transaction. |
| currency | The currency of the funds at the origin. |
| description | The name of the sender. |
| fee | The Bitcoin network Fee, if origin is in BTC but destination is not, or is a non-Uphold Bitcoin Address. |
| isMember | A boolean signaling if the origin user has completed the membership process. |
| node | The details about the transaction origin node. |
| rate | The rate for conversion between origin and destination, as expressed in the currency at origin (the inverse of destination.rate). |
| sources | The transactions where the value was originated from (id and amount). |
| type | The type of endpoint. Possible values are card and external. |
The destination of a transaction has its own set of properties describing how the destination is affected, which include:
| Property | Description |
|---|---|
| CardId | The ID of the card credited. Only visible to the user who receives the transaction. |
| amount | The amount credited, including commissions and fees. |
| base | The amount to credit, before commissions or fees. |
| commission | The commission charged by Uphold to process the transaction. Commissions are only charged when currency is converted into a different denomination. |
| currency | The denomination of the funds at the time they were sent/received. |
| description | The name of the recipient. In the case where money is sent via email, the description will contain the email address of the recipient. |
| fee | The Bitcoin network Fee, if destination is a BTC address but origin is not. |
| isMember | A boolean signaling if the destination user has completed the membership process. |
| node | The details about the transaction destination node. |
| rate | The rate for conversion between origin and destination, as expressed in the currency at destination (the inverse of origin.rate). |
| type | The type of endpoint. Possible values are email, card and external. |
An example user encoded in JSON looks like this:
{
"address": {
"city": "Ryleighfort",
"line1": "32167 Mohr Land",
"line2": "Suite 257",
"zipCode": "47890"
},
"balances": {
"currencies": {
"BTC": {
"amount": "4500.00",
"balance": "5.00",
"currency": "USD",
"rate": "900.00000"
},
"EUR": {
"amount": "180.89",
"balance": "154.88",
"currency": "USD",
"rate": "1.16795"
},
"USD": {
"amount": "17710.05",
"balance": "17710.05",
"currency": "USD",
"rate": "1.00000"
}
},
"total": "22390.94"
},
"birthdate": "2000-09-27",
"country": "US",
"currencies": [
"BTC",
"CNY",
"ETH",
"EUR",
"GBP",
"JPY",
"LTC",
"USD",
"XAU",
"XRP"
],
"email": "[email protected]",
"firstName": "Malika",
"id": "21e65c4d-55e4-41be-97a1-ff38d8f3d945",
"lastName": "Koss",
"memberAt": "2018-08-01T09:53:44.293Z",
"name": "Malika Koss",
"phones": [{
"e164Masked": "+XXXXXXXXX66",
"id": "abefe0b6-2f5d-45ba-97ac-3b07b08595a3",
"internationalMasked": "+X XXX-XXX-XX66",
"nationalMasked": "(XXX) XXX-XX66",
"primary": true,
"verified": true
}],
"settings": {
"currency": "USD",
"hasMarketingConsent": false,
"hasNewsSubscription": false,
"intl": {
"dateTimeFormat": {
"locale": "en-US"
},
"language": {
"locale": "en-US"
},
"numberFormat": {
"locale": "en-US"
}
},
"otp": {
"login": {
"enabled": true
},
"transactions": {
"send": {
"enabled": true
},
"transfer": {
"enabled": false
},
"withdraw": {
"crypto": {
"enabled": true
}
}
},
"vmc": {
"enabled": true
}
}
},
"state": "US-UT",
"status": "ok",
"type": "individual",
"verifications": {}
}The user object contains most of the information we have on record relating to the currently logged in user.
| Property | Description |
|---|---|
| memberAt | The date when the user became a verified member. |
memberAt field can be null if the user hasn't completed the membership process.
Any information needed for membership will be included in the verifications field.
Note that this is distinct from the pending user status, which is related to the initial signup process.
- otp.login.enabled - This will prompt the user to input an OTP token when creating an OAuth token.
- otp.transactions.send.enabled - This will prompt the user to input an OTP token when creating a transaction to another user.
- otp.transactions.transfer.enabled - This will prompt the user to input an OTP token when transacting between the user's own cards.
- otp.transactions.withdraw.crypto.enabled - This will prompt the user to input an OTP token when withdrawing to the bitcoin network.
- otp.vmc.enabled - This will prompt the user to input an OTP token when using VMCs.
We communicate a number of different user statuses through our API. At a high-level users can be in one of four statuses:
- blocked - This status is present when a user has violated our terms of service.
- ok - Everything is ay-ok.
- pending - This status applies to a user that is in the process of creating an account; it means the signup process is not yet finalized.
- restricted - This status means the user is allowed to login to the application, deposit or receive money, and perform trades, but they are not permitted to withdraw nor send money to other users. This status exists to allow users to satisfy additional data requirements. In this status users are unable to login or access the product.
The verifications field can help communicate the reasons for a given user status, or what's missing to complete the membership process.
These verifications have permissible values and in some cases, an associated reason.
Here is an overview of the verifications field:
| Flag | Permissible Values | Reason | Description |
|---|---|---|---|
| address | null, required | n/a | Required for individual users. |
| birthdate | required | n/a | Whether the user needs to provide their date of birth. |
| customerDueDiligence | null, optional, required | n/a | CDD is required if the user is from an European country otherwise, it's optional. |
| documents | null, optional, required | identity-country-mismatch, invalid, missing | Required when the user must submit SSN or Tax ID. |
| unconfirmed | n/a | Whether the user needs to confirm their email. | |
| identity | required, retry, review, running | n/a | The status of identity verification during the membership application process. |
| location | blocked, required | country, state | Whether the user has specified their location, which can be a blocked country/state. |
| permanentAddress | null, required | n/a | Required for non-US citizens with US residence. |
| phone | required, unconfirmed | n/a | The status of phone number verification. |
| terms | required | updated | Whether the user has accepted the latest version of the terms of service. |
| termsEquities | null, required | n/a | Required when the user hasn't accepted the terms of service for equities trading. |
| usTaxPayer | null, required | n/a | Required for non-US citizens with US residence. |