user_token or business_token for both resources.
Note
The
The
/users and /businesses resources also have address fields. Those are used for other purposes, such as KYC identity verification or as shipping addresses for physical cards.Create address
Action:POSTEndpoint:
/fundingsources/addresses
Use this endpoint to create an address resource.
When creating the address, you must pass the token of either an existing user in the user_token field or an existing business in the business_token field. Do not pass both.
Request body
| Fields | Description |
|---|---|
| active boolean Optional | Specifies whether the address is active. Allowable Values: true, falseDefault value: true |
| address_1 string Required | Street name and number of the address. Allowable Values: 255 char max |
| address_2 string Optional | Additional address information. Allowable Values: 255 char max |
| business_token string Optional | Unique identifier of the business account holder. This token is required if a user_token is not specified.Allowable Values: 1–36 chars |
| city string Required | City of the address. Allowable Values: 40 char max |
| country string Required | Country of the address. Allowable Values: 1–40 chars |
| first_name string Required | First name or given name of the account holder. Allowable Values: 40 char max |
| is_default_address boolean Optional | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.Allowable Values: true, falseDefault value: false |
| last_name string Required | Last name or family name of the account holder. Allowable Values: 40 char max |
| phone string Optional | Telephone number of the account holder. Allowable Values: 255 char max |
| postal_code string Optional | Postal code of the address. Allowable Values: 10 char max |
| state string Required | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| token string Optional | Unique identifier of the address. If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 1–36 chars |
| user_token string Optional | Unique identifier of the user account holder. This token is required if a business_token is not specified.Allowable Values: 1–36 chars |
| zip string Optional | United States ZIP code. This field is required if postal_code is not specified.Allowable Values: 10 char max |
Sample request body
JSON
{
"token": "my_funding_source_address_biz_01",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"business_token": "my_business_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "1234 Grove Street"
}
Response body
| Fields | Description |
|---|---|
| active boolean Conditionally returned | Specifies whether the address is active. This field is returned if it exists in the resource. Allowable Values: true, false |
| address_1 string Returned | Street name and number of the address. Allowable Values: 255 char max |
| address_2 string Conditionally returned | Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| business_token string Conditionally returned | Unique identifier of the business account holder. This token is returned if a user_token is not specified.Allowable Values: 1–36 chars |
| city string Returned | City of the address. Allowable Values: 40 char max |
| country string Returned | Country of the address. Allowable Values: 1–40 chars |
| created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| first_name string Returned | First or given name of the cardholder. Allowable Values: 40 char max |
| is_default_address boolean Conditionally returned | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.This field is returned if it exists in the resource. Allowable Values: true, false |
| last_modified_time datetime Returned | Date and time when the resource was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_name string Returned | Last name or family name of the cardholder. Allowable Values: 40 char max |
| phone string Conditionally returned | Telephone number of the cardholder. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| postal_code string Returned | Postal code of the address. Allowable Values: 10 char max |
| state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| token string Returned | Unique identifier of the address object. Allowable Values: 1–36 chars |
| user_token string Conditionally returned | Unique identifier of the user account holder. This token is returned if a business_token is not specified.Allowable Values: 1–36 chars |
| zip string Returned | United States ZIP code of the address. This field is returned if postal_code is not specified.Allowable Values: 10 char max |
Sample response body
JSON
{
"business_token": "my_business_01",
"token": "my_funding_source_address_biz_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "1234 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": true,
"active": true,
"created_time": "2023-02-20T20:04:13Z",
"last_modified_time": "2023-02-20T20:04:13Z"
}
List business addresses
Action:GETEndpoint:
/fundingsources/addresses/business/{business_token}
Use this endpoint to list existing addresses for a business. This endpoint supports field filtering.
URL path parameters
| Fields | Description |
|---|---|
| business_token string Required | Unique identifier of the business account holder. Send a GET request to /businesses to retrieve business tokens.Allowable Values: Existing business resource token |
URL query parameters
| Fields | Description |
|---|---|
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
| data array of objects Conditionally returned | Array of address objects. Objects are returned as appropriate to your query. Allowable Values: Valid data array of one or more address objects |
| data[].active boolean Conditionally returned | Specifies whether the address is active. This field is returned if it exists in the resource. Allowable Values: true, false |
| data[].address_1 string Returned | Street name and number of the address. Allowable Values: 255 char max |
| data[].address_2 string Conditionally returned | Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| data[].business_token string Conditionally returned | Unique identifier of the business account holder. This token is returned if a user_token is not specified.Allowable Values: 1–36 chars |
| data[].city string Returned | City of the address. Allowable Values: 40 char max |
| data[].country string Returned | Country of the address. Allowable Values: 1–40 chars |
| data[].created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].first_name string Returned | First or given name of the cardholder. Allowable Values: 40 char max |
| data[].is_default_address boolean Conditionally returned | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.This field is returned if it exists in the resource. Allowable Values: true, false |
| data[].last_modified_time datetime Returned | Date and time when the resource was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_name string Returned | Last name or family name of the cardholder. Allowable Values: 40 char max |
| data[].phone string Conditionally returned | Telephone number of the cardholder. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| data[].postal_code string Returned | Postal code of the address. Allowable Values: 10 char max |
| data[].state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| data[].token string Returned | Unique identifier of the address object. Allowable Values: 1–36 chars |
| data[].user_token string Conditionally returned | Unique identifier of the user account holder. This token is returned if a business_token is not specified.Allowable Values: 1–36 chars |
| data[].zip string Returned | United States ZIP code of the address. This field is returned if postal_code is not specified.Allowable Values: 10 char max |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"business_token": "my_business_01",
"token": "my_funding_source_address_bus_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "1234 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": true,
"active": true,
"created_time": "2023-02-26T21:34:42Z",
"last_modified_time": "2023-02-27T18:55:59Z"
},
{
"business_token": "my_business_01",
"token": "my_funding_source_address_bus_02",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "5678 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": false,
"active": true,
"created_time": "2023-02-25T19:48:30Z",
"last_modified_time": "2023-03-25T10:17:38Z"
}
]
}
Lists all addresses for a user
Action:GETEndpoint:
/fundingsources/addresses/user/{user_token}
Use this endpoint to list existing addresses for a user. This endpoint supports field filtering.
URL path parameters
| Fields | Description |
|---|---|
| user_token string Required | Unique identifier of the user account holder. Allowable Values: Existing user resource token |
URL query parameters
| Fields | Description |
|---|---|
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
Response body
| Fields | Description |
|---|---|
| count integer Conditionally returned | Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10 |
| data array of objects Conditionally returned | Array of address objects. Objects are returned as appropriate to your query. Allowable Values: Valid data array of one or more address objects |
| data[].active boolean Conditionally returned | Specifies whether the address is active. This field is returned if it exists in the resource. Allowable Values: true, false |
| data[].address_1 string Returned | Street name and number of the address. Allowable Values: 255 char max |
| data[].address_2 string Conditionally returned | Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| data[].business_token string Conditionally returned | Unique identifier of the business account holder. This token is returned if a user_token is not specified.Allowable Values: 1–36 chars |
| data[].city string Returned | City of the address. Allowable Values: 40 char max |
| data[].country string Returned | Country of the address. Allowable Values: 1–40 chars |
| data[].created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].first_name string Returned | First or given name of the cardholder. Allowable Values: 40 char max |
| data[].is_default_address boolean Conditionally returned | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.This field is returned if it exists in the resource. Allowable Values: true, false |
| data[].last_modified_time datetime Returned | Date and time when the resource was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| data[].last_name string Returned | Last name or family name of the cardholder. Allowable Values: 40 char max |
| data[].phone string Conditionally returned | Telephone number of the cardholder. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| data[].postal_code string Returned | Postal code of the address. Allowable Values: 10 char max |
| data[].state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| data[].token string Returned | Unique identifier of the address object. Allowable Values: 1–36 chars |
| data[].user_token string Conditionally returned | Unique identifier of the user account holder. This token is returned if a business_token is not specified.Allowable Values: 1–36 chars |
| data[].zip string Returned | United States ZIP code of the address. This field is returned if postal_code is not specified.Allowable Values: 10 char max |
| end_index integer Conditionally returned | Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
| is_more boolean Conditionally returned | A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.This field is returned if there are resources in your returned array. Allowable Values: true, false |
| start_index integer Conditionally returned | Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"business_token": "my_user_01",
"token": "my_funding_source_address_user_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "1234 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": true,
"active": true,
"created_time": "2023-02-27T21:34:42Z",
"last_modified_time": "2023-02-28T18:55:59Z"
},
{
"business_token": "my_user_01",
"token": "my_funding_source_address_user_02",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "5678 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": false,
"active": true,
"created_time": "2023-02-25T19:48:30Z",
"last_modified_time": "2023-03-25T19:48:30Z"
}
]
}
Retrieve address
Action:GETEndpoint:
/fundingsources/addresses/{funding_source_address_token}
Use this endpoint to retrieve a funding source address.
URL path parameters
| Fields | Description |
|---|---|
| funding_source_address_token string Required | Unique identifier of the funding source address. Allowable Values: Existing funding source address token |
Response body
| Fields | Description |
|---|---|
| active boolean Conditionally returned | Specifies whether the address is active. This field is returned if it exists in the resource. Allowable Values: true, false |
| address_1 string Returned | Street name and number of the address. Allowable Values: 255 char max |
| address_2 string Conditionally returned | Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| business_token string Conditionally returned | Unique identifier of the business account holder. This token is returned if a user_token is not specified.Allowable Values: 1–36 chars |
| city string Returned | City of the address. Allowable Values: 40 char max |
| country string Returned | Country of the address. Allowable Values: 1–40 chars |
| created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| first_name string Returned | First or given name of the cardholder. Allowable Values: 40 char max |
| is_default_address boolean Conditionally returned | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.This field is returned if it exists in the resource. Allowable Values: true, false |
| last_modified_time datetime Returned | Date and time when the resource was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_name string Returned | Last name or family name of the cardholder. Allowable Values: 40 char max |
| phone string Conditionally returned | Telephone number of the cardholder. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| postal_code string Returned | Postal code of the address. Allowable Values: 10 char max |
| state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| token string Returned | Unique identifier of the address object. Allowable Values: 1–36 chars |
| user_token string Conditionally returned | Unique identifier of the user account holder. This token is returned if a business_token is not specified.Allowable Values: 1–36 chars |
| zip string Returned | United States ZIP code of the address. This field is returned if postal_code is not specified.Allowable Values: 10 char max |
Sample response body
JSON
{
"business_token": "my_business_01",
"token": "my_funding_source_address_biz_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "1234 Grove Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": true,
"active": true,
"created_time": "2023-02-20T20:04:13Z",
"last_modified_time": "2023-02-20T20:04:13Z"
}
Update address
Action:PUTEndpoint:
/fundingsources/addresses/{funding_source_address_token}
Use this endpoint to update an address.
URL path parameters
| Fields | Description |
|---|---|
| funding_source_address_token string Required | Unique identifier of the funding source address. Allowable Values: Existing funding source address token |
Request body
| Fields | Description |
|---|---|
| active boolean Optional | Specifies whether the address is active. Allowable Values: true, falseDefault value: false |
| address_1 string Optional | Street name and number of the address. Allowable Values: 255 char max |
| address_2 string Optional | Additional address information. Allowable Values: 255 char max |
| city string Optional | City of the address. Allowable Values: 40 char max |
| country string Optional | Country of the address. Allowable Values: 40 char max |
| first_name string Optional | First name or given name of the account holder. Allowable Values: 40 char max |
| is_default_address boolean Optional | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.Allowable Values: true, falseDefault value: false |
| last_name string Optional | Last name or family name of the account holder. Allowable Values: 40 char max |
| phone string Optional | Telephone number of the account holder. Allowable Values: 255 char max |
| postal_code string Optional | Postal code of the address. Allowable Values: 10 char max |
| state string Optional | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| zip string Optional | United States ZIP code of the address. Allowable Values: 10 char max |
Sample request body
JSON
{
"address_1": "333 Elm Street"
}
Response body
| Fields | Description |
|---|---|
| active boolean Conditionally returned | Specifies whether the address is active. This field is returned if it exists in the resource. Allowable Values: true, false |
| address_1 string Returned | Street name and number of the address. Allowable Values: 255 char max |
| address_2 string Conditionally returned | Additional address information. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| business_token string Conditionally returned | Unique identifier of the business account holder. This token is returned if a user_token is not specified.Allowable Values: 1–36 chars |
| city string Returned | City of the address. Allowable Values: 40 char max |
| country string Returned | Country of the address. Allowable Values: 1–40 chars |
| created_time datetime Returned | Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| first_name string Returned | First or given name of the cardholder. Allowable Values: 40 char max |
| is_default_address boolean Conditionally returned | A value of true specifies that this address is the default address used by the account holder’s funding source. If this is the account holder’s only address, it is used as the default regardless of this field’s setting.This field is returned if it exists in the resource. Allowable Values: true, false |
| last_modified_time datetime Returned | Date and time when the resource was last modified, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ |
| last_name string Returned | Last name or family name of the cardholder. Allowable Values: 40 char max |
| phone string Conditionally returned | Telephone number of the cardholder. This field is returned if it exists in the resource. Allowable Values: 255 char max |
| postal_code string Returned | Postal code of the address. Allowable Values: 10 char max |
| state string Returned | Two-character state, provincial, or territorial abbreviation. For the complete list, see Valid state, provincial, territorial, and federal abbreviations. Allowable Values: 2 char max |
| token string Returned | Unique identifier of the address object. Allowable Values: 1–36 chars |
| user_token string Conditionally returned | Unique identifier of the user account holder. This token is returned if a business_token is not specified.Allowable Values: 1–36 chars |
| zip string Returned | United States ZIP code of the address. This field is returned if postal_code is not specified.Allowable Values: 10 char max |
Sample response body
JSON
{
"business_token": "my_business_01",
"token": "my_funding_source_address_biz_01",
"first_name": "Jane",
"last_name": "Doe",
"address_1": "333 Elm Street",
"city": "Berkeley",
"state": "CA",
"postal_code": "94705",
"zip": "94705",
"country": "USA",
"phone": "5104444444",
"is_default_address": true,
"active": true,
"created_time": "2023-02-20T20:04:13Z",
"last_modified_time": "2023-02-28T16:00:00Z"
}