DOCS
Support

Marqeta Home

/
Guides
Core API Reference
DiVA API Reference
Core API Explorer

5 minute read

November 10, 2020

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
Copy section link

Action: POST
Endpoint: /fundingsources/addresses

Develop Now!

Sign in and use your sandbox to access the API Explorer

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.

Body field details
Copy section link

Fields Description

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:

36 char max

user_token OR business_token

string
Required

Specifies the account holder to associate with this address. Pass either user_token or business_token, not both. This value cannot be updated.

Allowable Values:

Existing user or business token.

Send a GET request to /users to retrieve user tokens or to /businesses to retrieve business tokens.

first_name

string
Required

First name.

Allowable Values:

40 char max

last_name

string
Required

Last name.

Allowable Values:

40 char max

address_1

string
Required

Street address.

Allowable Values:

255 char max

address_2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Required

City.

Allowable Values:

40 char max

state

string
Required

State.

Allowable Values:

2 char max

postal_code

string
Required

Postal code.

Allowable Values:

10 char max

country

string
Required

Country.

Allowable Values:

40 char max

is_default_address

boolean
Optional

The value 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:
true if no other address is set as the default; otherwise, false

phone

string
Optional

Telephone number.

Allowable Values:

255 char max

active

boolean
Optional

Specifies whether the address is active.

Allowable Values:

true, false

Default value:
false

Sample request body
Copy section link

{
  "token": "my_funding_source_address_biz_04_02",
  "city": "Berkeley",
  "state": "CA",
  "postal_code": "94705",
  "country": "USA",
  "phone": "5104444444",
  "business_token": "my_business_04",
  "first_name": "My",
  "last_name": "Biz",
  "address_1": "3333 Bogus Way"
}

Is this helpful?

Sample response body
Copy section link

{
  "business_token": "my_business_04",
  "token": "my_funding_source_address_biz_04_02",
  "first_name": "My",
  "last_name": "Biz",
  "address_1": "3333 Bogus Way",
  "city": "Berkeley",
  "state": "CA",
  "postal_code": "94705",
  "country": "USA",
  "phone": "5104444444",
  "is_default_address": true,
  "active": true,
  "created_time": "2019-12-20T20:04:13Z",
  "last_modified_time": "2019-12-20T20:04:13Z"
}

Is this helpful?

Retrieve address
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to retrieve a funding source address.

URL path parameters
Copy section link

Fields Description

funding_source_address_token

string
Required

The token identifying the funding source address to retrieve.

Allowable Values:

Existing funding source address token.

Send a GET request to /fundingsource/addresses/user/{user_token} or /fundingsource/addresses/business/{business_token} to retrieve existing address tokens for users or businesses.

Sample response body
Copy section link

{
  "business_token": "my_business_04",
  "token": "my_funding_source_address_biz_04_02",
  "first_name": "My",
  "last_name": "Biz",
  "address_1": "3333 Bogus Way",
  "city": "Berkeley",
  "state": "CA",
  "postal_code": "94705",
  "country": "USA",
  "phone": "5104444444",
  "is_default_address": true,
  "active": true,
  "created_time": "2019-12-20T20:04:13Z",
  "last_modified_time": "2019-12-20T20:04:13Z"
}

Is this helpful?

Update address
Copy section link

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

Develop Now!

Sign in and use your sandbox to access the API Explorer

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

URL path parameters
Copy section link

Fields Description

funding_source_address_token

string
Required

The token identifying the funding source address to update.

Allowable Values:

Existing funding source address token.

Send a GET request to /fundingsource/addresses/user/{user_token} or /fundingsource/addresses/business/{business_token} to retrieve existing address tokens for users or businesses.

Body field details
Copy section link

Fields Description

first_name

string
Required

First name.

Allowable Values:

40 char max

last_name

string
Required

Last name.

Allowable Values:

40 char max

address_1

string
Required

Street address.

Allowable Values:

255 char max

address_2

string
Optional

Additional address information.

Allowable Values:

255 char max

city

string
Required

City.

Allowable Values:

40 char max

state

string
Required

State.

Allowable Values:

2 char max

postal_code

string
Required

Postal code.

Allowable Values:

10 char max

country

string
Required

Country.

Allowable Values:

40 char max

is_default_address

boolean
Optional

The value 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:
true if no other address is set as the default; otherwise, false

phone

string
Optional

Telephone number.

Allowable Values:

255 char max

active

boolean
Optional

Specifies whether the address is active.

Allowable Values:

true, false

Default value:
false

Sample request body
Copy section link

{
  "address_1": "333 Elm Street"
}

Is this helpful?

Sample response body
Copy section link

{
  "business_token": "my_business_04",
  "token": "my_funding_source_address_biz_04_02",
  "first_name": "My",
  "last_name": "Biz",
  "address_1": "333 Elm Street",
  "city": "Berkeley",
  "state": "CA",
  "postal_code": "94705",
  "country": "USA",
  "phone": "5104444444",
  "is_default_address": true,
  "active": true,
  "created_time": "2019-12-20T20:04:13Z",
  "last_modified_time": "2019-12-20T20:04:13Z"
}

Is this helpful?

List user addresses
Copy section link

Action: GET
Endpoint: /fundingsources/addresses/user/{user_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list existing addresses for a user. This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

user_token

string
Required

Identifies the user whose addresses you want to list.

Allowable Values:

Existing user token.

Send a GET request to /users to retrieve existing user tokens.

Sample response body
Copy section link

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "user_token": "my_user_01",
      "token": "my_funding_source_address_user_01",
      "first_name": "Owl",
      "last_name": "Bird",
      "address_1": "3333 Bogus Way",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94705",
      "country": "USA",
      "phone": "5104444444",
      "is_default_address": true,
      "active": true,
      "created_time": "2019-10-27T18:59:03Z",
      "last_modified_time": "2019-10-27T18:59:03Z"
    },
    {
      "user_token": "my_user_01",
      "token": "my_funding_source_address_user_01_02",
      "first_name": "Owl",
      "last_name": "Bird",
      "address_1": "3377 Redwood Drive",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94705",
      "country": "USA",
      "phone": "5104444444",
      "is_default_address": false,
      "active": true,
      "created_time": "2019-12-21T00:07:17Z",
      "last_modified_time": "2019-12-21T00:07:17Z"
    }
  ]
}

Is this helpful?

List business addresses
Copy section link

Action: GET
Endpoint: /fundingsources/addresses/business/{business_token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Use this endpoint to list existing addresses for a business. This endpoint supports field filtering.

URL path parameters
Copy section link

Fields Description

business_token

string
Required

Identifies the business whose addresses you want to list.

Allowable Values:

Existing business token.

Send a GET request to /businesses to retrieve existing business tokens.

Sample response body
Copy section link

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "business_token": "my_business_01",
      "token": "my_funding_source_address_biz_01",
      "first_name": "My",
      "last_name": "Biz",
      "address_1": "3333 Bogus Way",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94705",
      "country": "USA",
      "phone": "5104444444",
      "is_default_address": true,
      "active": true,
      "created_time": "2016-12-26T21:34:42Z",
      "last_modified_time": "2016-12-27T18:55:59Z"
    },
    {
      "business_token": "my_business_01",
      "token": "my_funding_source_address_biz_03",
      "first_name": "My",
      "last_name": "Biz",
      "address_1": "77 Howdy Street",
      "city": "Berkeley",
      "state": "CA",
      "postal_code": "94705",
      "country": "USA",
      "phone": "5104444444",
      "is_default_address": false,
      "active": false,
      "created_time": "2016-12-20T19:48:30Z",
      "last_modified_time": "2016-12-20T19:48:30Z"
    }
  ]
}

Is this helpful?

Related Materials

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.