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

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Type	Required	Description
user_id	path	string		Unique user ID to use for this user.

Request

Field	Type	Required	Description
address_line_1	string		The first address line.
address_line_2	string		The second address line.
address_type	string		The type of address, e.g., "residential".
postal_code	string		The postal/zip code of the address.
city	string		The city or town of the address, e.g., "Chicago".
first_name	string		The user's first name. Note this field does not support special characters /:<>$%?.
last_name	string		The user's last name. Note this field does not support special characters /:<>$%?.
phone_number	string		The user's phone number.
locale	string		The user's locale in IETF Language Tag format. Example: en-US.

Request examples

cURL

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",
  "city": "string",
  "first_name": "string",
  "last_name": "string",
  "phone_number": "string",
  "locale": "string"
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/users/{user_id}/addresses")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"address_line_1\": \"string\",\n  \"address_line_2\": \"string\",\n  \"address_type\": \"string\",\n  \"postal_code\": \"string\",\n  \"city\": \"string\",\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"phone_number\": \"string\",\n  \"locale\": \"string\"\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"address_line_1\": \"string\",\n  \"address_line_2\": \"string\",\n  \"address_type\": \"string\",\n  \"postal_code\": \"string\",\n  \"city\": \"string\",\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"phone_number\": \"string\",\n  \"locale\": \"string\"\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("POST", "/v2/fulfillment/users/{user_id}/addresses", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/fulfillment/users/{user_id}/addresses"

	payload := strings.NewReader("{\n  \"address_line_1\": \"string\",\n  \"address_line_2\": \"string\",\n  \"address_type\": \"string\",\n  \"postal_code\": \"string\",\n  \"city\": \"string\",\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"phone_number\": \"string\",\n  \"locale\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
address	CreateAddress		The address used for validation.
user_id	string		The ID of the user.

CreateAddress Object

Field	Type	Required	Description
address_line_1	string		The first address line.
postal_code	string		The postal/zip code of the address.
flags	Flags		Additional properties of the address.

Flags Object

Field	Type	Required	Description
long_distance_delivery	boolean		Whether a delivery to the address will be a long distance delivery.

Response examples

200 Success

200 User and address created

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

200 User and address created and user info updated

{
  "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 Code	Cause	Error Message	Error Code	Error Meta
400	Invalid input*	"There were issues with your request"	9999	Not applicable
400	Address not serviceable	"Address is not serviceable."	1001	{"key":"address_line_1"}
400	Postal code not found	"Address is not serviceable."	1001	{"key":"address_line_1"}
400	Invalid address	"invalid_address"	1001	{"key":"address"}
400	Invalid first name	"First name is invalid"	1001	{"key":"first_name"}
400	Invalid last name	"Last name is invalid"	1001	{"key":"last_name"}
400	User with invalid phone number	"Phone is invalid"	1001	{"key":"phone"}
400	Invalid locale provided	"Unsupported locale"	1001	{"key":"locale"}
400	Address line 1 to long	"is too long (maximum is 255 characters)"	1001	{"key":"address_line_1"}
400	Address line 2 to long	"is too long (maximum is 255 characters)"	1001	{"key":"address_line_2"}
400	Address contains PO box	"address contains PO Box"	1001	{"key":"address"}
400	Missing postal code	"can't be blank"	1001	{"key":"postal_code"}
400	Retry later	"Please try again in a little while"	2003	Not applicable
403	User Not Active	"User Not Active"	null	Not applicable

* Multiple error