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

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.

Body field details

Name Type Required? Description Allowable Values
token string No 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. 36 char max
user_token

OR

business_token
string Yes Specifies the account holder to associate with this address. Pass either user_token or business_token, not both. This value cannot be updated. Existing user or business token.

Issue a GET to /users to retrieve user tokens or to /businesses to retrieve business tokens.
first_name string Yes First name. 255 char max
last_name string Yes Last name. 255 char max
address_1 string Yes Street address. 255 char max
address_2 string No Additional address information. 255 char max
city string Yes City. 40 char max
state string Yes State. 2 char max
postal_code string Yes Postal code. 10 char max
country string Yes Country. 40 char max
is_default_address boolean No 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. true | false

Default: "true" if no other address is set as the default; otherwise, "false"
phone string No Telephone number. 255 char max
active boolean No Specifies whether the address is active. true | false

Default: false

Sample request body

{
"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"
}

Sample response body

{
"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"
}


Retrieve address

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

Use this endpoint to retrieve a funding source address.

URL path parameters

Name Type Required? Description Allowable Values
funding_source_address_token string Yes The token identifying the funding source address to retrieve. Existing funding source address token.

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

Sample response body

{
"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"
}


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

Name Type Required? Description Allowable Values
funding_source_address_token string Yes The token identifying the funding source address to update. Existing funding source address token.

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

Body field details

Name Type Required? Description Allowable Values
first_name string Yes First name. 255 char max
last_name string Yes Last name. 255 char max
address_1 string Yes Street address. 255 char max
address_2 string No Additional address information. 255 char max
city string Yes City. 40 char max
state string Yes State. 2 char max
postal_code string Yes Postal code. 10 char max
country string Yes Country. 40 char max
is_default_address boolean No 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. true | false

Default: "true" if no other address is set as the default; otherwise, "false"
phone string No Telephone number. 255 char max
active boolean No Specifies whether the address is active. true | false

Default: false

Sample request body

{
"address_1": "333 Elm Street"
}

Sample response body

{
"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"
}


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

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user whose addresses you want to list. Existing user token.

Issue a GET to /users to retrieve existing user tokens.

Sample response body

{
"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"
}
]
}


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

Name Type Required? Description Allowable Values
business_token string Yes Identifies the business whose addresses you want to list. Existing business token.

Issue a GET to /businesses to retrieve existing business tokens.

Sample response body

{
"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"
}
]
}