Skip to main content

Create a Connect user and validate an address

POST /v2/fulfillment/users/{user_id}/addresses

Creates a Connect user account and validates the address provided in the request. Use this endpoint for last mile delivery orders or for delivery orders where you want to validate an address early in the flow. The user ID is generated by your site and can be any unique identifier, such as a login name, loyalty ID, or email address. For more information about users, see create a user.

If a user account with the given user_id already exists, the address is validated and associated with the existing user. The response contains the existing user's ID and the validated street address and postal code. If the address is further than 30 minutes away from the closest stores, the long_distance_delivery flag is set to true.

When you create an order with this user_id, ensure that you use the validated address.

Security

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters

NameInTypeRequiredDescription
user_idpathstringRequiredUnique user ID to use for this user.

Request

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
address_line_2stringOptionalThe second address line.
address_typestringOptionalThe type of address, e.g., "residential".
postal_codestringRequiredThe postal/zip code of the address.
first_namestringOptionalThe user's first name. Note this field does not support special characters /:<>$%?.
last_namestringOptionalThe user's last name. Note this field does not support special characters /:<>$%?.
phone_numberstringOptionalThe user's phone number.
localestringOptionalThe user's locale in IETF Language Tag format. Example: en-US.

Request examples

curl --request POST \
--url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/addresses' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"address_line_1": "string",
"address_line_2": "string",
"address_type": "string",
"postal_code": "string",
"first_name": "string",
"last_name": "string",
"phone_number": "string",
"locale": "string"
}'

Response

FieldTypeRequiredDescription
addressCreateAddressOptionalThe address used for validation.
user_idstringOptionalThe ID of the user.

CreateAddress Object

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
postal_codestringRequiredThe postal/zip code of the address.
flagsFlagsOptionalAdditional properties of the address.

Flags Object

FieldTypeRequiredDescription
long_distance_deliverybooleanOptionalWhether a delivery to the address will be a long distance delivery.

Response examples

200 Success

{
"address": {
"address_line_1": "499 Gainsville",
"postal_code": "81910"
},
"user_id": "1234567890"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid input*"There were issues with your request"9999Not applicable
400Address not serviceable"Address is not serviceable."1001{"key":"address_line_1"}
400Postal code not found"Address is not serviceable."1001{"key":"address_line_1"}
400Invalid address"invalid_address"1001{"key":"address"}
400Invalid first name"First name is invalid"1001{"key":"first_name"}
400Invalid last name"Last name is invalid"1001{"key":"last_name"}
400Invalid locale provided"Unsupported locale"1001{"key":"locale"}
400Address line 1 to long"is too long (maximum is 255 characters)"1001{"key":"address_line_1"}
400Address line 2 to long"is too long (maximum is 255 characters)"1001{"key":"address_line_2"}
400Address contains PO box"address contains PO Box"1001{"key":"address"}
* Multiple error