/
20 minute read
March 24, 2022

Addresses

Hidden

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 address.

Allowable Values:

255 char max

address_2

string
Optional

Additional address information.

Allowable Values:

255 char max

business_token

string
Optional

The 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.

Allowable Values:

40 char max

country

string
Required

Country.

Allowable Values:

1–40 chars

first_name

string
Required

First name.

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.

Allowable Values:

40 char max

phone

string
Optional

Telephone number.

Allowable Values:

255 char max

postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

state

string
Required

Two-character state, province, or territorial abbreviation.

For a complete list of valid state and province abbreviations, see Valid state, provincial, and territorial abbreviations.

Allowable Values:

2 char max

token

string
Optional

The 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

The 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

The United States ZIP code. This field is required if postal_code is not specified.

Allowable Values:

10 char max

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

active

boolean
Conditionally returned

Specifies whether the address is active.

Allowable Values:

true, false

address_1

string
Returned

Street address.

Allowable Values:

255 char max

address_2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

business_token

string
Conditionally returned

The 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.

Allowable Values:

40 char max

country

string
Returned

Country.

Allowable Values:

1–40 chars

created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

first_name

string
Returned

First name

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.

Allowable Values:

true, false

last_modified_time

datetime
Returned

The date and time when the resource was last modified, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_name

string
Returned

Last name.

Allowable Values:

40 char max

phone

string
Conditionally returned

Telephone number.

Allowable Values:

255 char max

postal_code

string
Returned

Postal code.

Allowable Values:

10 char max

state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

token

string
Returned

The unique identifier of the address object.

Allowable Values:

1–36 chars

user_token

string
Conditionally returned

The 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

The United States ZIP code. This field is returned if postal_code is not specified.

Allowable Values:

10 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The unique identifier of the business account holder.

Allowable Values:

Existing business 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

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of cardholder_address_model objects.

Allowable Values:

Valid cardholder_address_model array

data[].active

boolean
Conditionally returned

Specifies whether the address is active.

Allowable Values:

true, false

data[].address_1

string
Returned

Street address.

Allowable Values:

255 char max

data[].address_2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].business_token

string
Conditionally returned

The 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.

Allowable Values:

40 char max

data[].country

string
Returned

Country.

Allowable Values:

1–40 chars

data[].created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].first_name

string
Returned

First name

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.

Allowable Values:

true, false

data[].last_modified_time

datetime
Returned

The date and time when the resource was last modified, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].last_name

string
Returned

Last name.

Allowable Values:

40 char max

data[].phone

string
Conditionally returned

Telephone number.

Allowable Values:

255 char max

data[].postal_code

string
Returned

Postal code.

Allowable Values:

10 char max

data[].state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

data[].token

string
Returned

The unique identifier of the address object.

Allowable Values:

1–36 chars

data[].user_token

string
Conditionally returned

The 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

The United States ZIP code. This field is returned if postal_code is not specified.

Allowable Values:

10 char max

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List user addresses

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

The unique identifier of the user account holder.

Allowable Values:

Existing user 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

The number of resources to retrieve.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of cardholder_address_model objects.

Allowable Values:

Valid cardholder_address_model array

data[].active

boolean
Conditionally returned

Specifies whether the address is active.

Allowable Values:

true, false

data[].address_1

string
Returned

Street address.

Allowable Values:

255 char max

data[].address_2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

data[].business_token

string
Conditionally returned

The 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.

Allowable Values:

40 char max

data[].country

string
Returned

Country.

Allowable Values:

1–40 chars

data[].created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].first_name

string
Returned

First name

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.

Allowable Values:

true, false

data[].last_modified_time

datetime
Returned

The date and time when the resource was last modified, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

data[].last_name

string
Returned

Last name.

Allowable Values:

40 char max

data[].phone

string
Conditionally returned

Telephone number.

Allowable Values:

255 char max

data[].postal_code

string
Returned

Postal code.

Allowable Values:

10 char max

data[].state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

data[].token

string
Returned

The unique identifier of the address object.

Allowable Values:

1–36 chars

data[].user_token

string
Conditionally returned

The 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

The United States ZIP code. This field is returned if postal_code is not specified.

Allowable Values:

10 char max

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The 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.

Allowable Values:

true, false

address_1

string
Returned

Street address.

Allowable Values:

255 char max

address_2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

business_token

string
Conditionally returned

The 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.

Allowable Values:

40 char max

country

string
Returned

Country.

Allowable Values:

1–40 chars

created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

first_name

string
Returned

First name

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.

Allowable Values:

true, false

last_modified_time

datetime
Returned

The date and time when the resource was last modified, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_name

string
Returned

Last name.

Allowable Values:

40 char max

phone

string
Conditionally returned

Telephone number.

Allowable Values:

255 char max

postal_code

string
Returned

Postal code.

Allowable Values:

10 char max

state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

token

string
Returned

The unique identifier of the address object.

Allowable Values:

1–36 chars

user_token

string
Conditionally returned

The 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

The United States ZIP code. This field is returned if postal_code is not specified.

Allowable Values:

10 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update address

Action: PUT
Endpoint: /fundingsources/addresses/{funding_source_address_token}

Use this endpoint to update an address. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters
Fields Description

funding_source_address_token

string
Required

The 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 address.

Allowable Values:

255 char max

address_2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Optional

City.

Allowable Values:

40 char max

country

string
Optional

Country.

Allowable Values:

40 char max

first_name

string
Optional

First name.

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.

Allowable Values:

40 char max

phone

string
Optional

Telephone number.

Allowable Values:

255 char max

postal_code

string
Optional

Postal code.

Allowable Values:

10 char max

state

string
Optional

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

zip

string
Optional

United States ZIP code

Allowable Values:

10 char max

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Response body
Fields Description

active

boolean
Conditionally returned

Specifies whether the address is active.

Allowable Values:

true, false

address_1

string
Returned

Street address.

Allowable Values:

255 char max

address_2

string
Conditionally returned

Additional address information.

Allowable Values:

255 char max

business_token

string
Conditionally returned

The 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.

Allowable Values:

40 char max

country

string
Returned

Country.

Allowable Values:

1–40 chars

created_time

datetime
Returned

The date and time when the resource was created, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

first_name

string
Returned

First name

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.

Allowable Values:

true, false

last_modified_time

datetime
Returned

The date and time when the resource was last modified, in UTC. 2022-02-26T20:03:05Z, for example.

Allowable Values:

Format: yyyy-MM-ddTHH:mm:ssZ

last_name

string
Returned

Last name.

Allowable Values:

40 char max

phone

string
Conditionally returned

Telephone number.

Allowable Values:

255 char max

postal_code

string
Returned

Postal code.

Allowable Values:

10 char max

state

string
Returned

Two-character state, province, or territorial abbreviation.

Allowable Values:

2 char max

token

string
Returned

The unique identifier of the address object.

Allowable Values:

1–36 chars

user_token

string
Conditionally returned

The 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

The United States ZIP code. This field is returned if postal_code is not specified.

Allowable Values:

10 char max

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter