/
20 minute read
November 30, 2022

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 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 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 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, 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

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
Copied

Is this helpful?

Yes
No

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 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:

Format: yyyy-MM-ddThh:mm:ssZ

first_name

string
Returned

First 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:

Format: yyyy-MM-ddThh:mm:ssZ

last_name

string
Returned

Last 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, province, or territorial abbreviation.

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

Unique identifier of the business account holder.

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 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:

Format: yyyy-MM-ddThh:mm:ssZ

data[].first_name

string
Returned

First 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:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_name

string
Returned

Last 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, province, or territorial abbreviation.

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
Copied

Is this helpful?

Yes
No

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 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:

Format: yyyy-MM-ddThh:mm:ssZ

data[].first_name

string
Returned

First 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:

Format: yyyy-MM-ddThh:mm:ssZ

data[].last_name

string
Returned

Last 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, province, or territorial abbreviation.

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

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 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:

Format: yyyy-MM-ddThh:mm:ssZ

first_name

string
Returned

First 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:

Format: yyyy-MM-ddThh:mm:ssZ

last_name

string
Returned

Last 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, province, or territorial abbreviation.

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
Copied

Is this helpful?

Yes
No

Updates the account holder address for a funding source

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

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 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 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 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, province, or territorial abbreviation.

Allowable Values:

2 char max

zip

string
Optional

United States ZIP code of the address.

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.

This field is returned if it exists in the resource.

Allowable Values:

true, false

address_1

string
Returned

Street 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:

Format: yyyy-MM-ddThh:mm:ssZ

first_name

string
Returned

First 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:

Format: yyyy-MM-ddThh:mm:ssZ

last_name

string
Returned

Last 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, province, or territorial abbreviation.

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
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter