DOCS

New!

Support
Sign in to get developer support

Marqeta Home

/
Developer Guides
Core API Reference
DiVA API Reference
Core API Explorer

5 minute read

October 2, 2019

Addresses

The address resource on the Marqeta platform performs the function of a billing address. An active address is required in order to use a payment card funding source. You associate such a funding source with an address by way of mutual association with the same account holder (either a user or business).

Note
Although the user and business resources also have address fields, these are used for other purposes such as KYC identity verification and the shipping address 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": "2016-12-20T20:04:13Z",
  "last_modified_time": "2016-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": "2016-12-20T20:04:13Z",
  "last_modified_time": "2016-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": "2016-12-20T20:04:13Z",
  "last_modified_time": "2016-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": "2016-10-27T18:59:03Z",
      "last_modified_time": "2016-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": "2016-12-21T00:07:17Z",
      "last_modified_time": "2016-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.