Addresses

The address resource is your billing address. An active address is required in order to use a payment card funding source. To associate an address with a funding source, use the same user_token or business_token for both resources.

Note
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: POST
Endpoint: /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`, `false` Default 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`, `false` Default 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: GET
Endpoint: /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: GET
Endpoint: /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: GET
Endpoint: /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: PUT
Endpoint: /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`, `false` Default 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`, `false` Default 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"
}

Core API Basics

SDKs

Credentials

Account Holders

Funding

Just-in-Time Funding

Cards

Digital Wallets

Spend Control

Accounts

Transactions

3D Secure

Real-Time Decisioning

Disputes

Digital Banking

Credit Programs

Credit Account Management

Credit Account Servicing

Credit Reward Accounts

Testing

Webhooks

​Create address

​Request body

​Sample request body

​Response body

​Sample response body

​List business addresses

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Lists all addresses for a user

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Retrieve address

​URL path parameters

​Response body

​Sample response body

​Update address

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

Create address

Request body

Sample request body

Response body

Sample response body

List business addresses

URL path parameters

URL query parameters

Response body

Sample response body

Lists all addresses for a user

URL path parameters

URL query parameters

Response body

Sample response body

Retrieve address

URL path parameters

Response body

Sample response body

Update address

URL path parameters

Request body

Sample request body

Response body

Sample response body