Create New Session
Creates a new session for processing a service address. This is typically the first endpoint called when starting a new address lookup flow.
Request Flow
- Submit service address components
- Receive a session token
- Use session token in the URL path for subsequent requests
Processing
Upon session creation, Hum AI agents begin:
- Validating and normalizing the address
- Geocoding the location
- Identifying available service providers
- Gathering plan and pricing information
Response Handling
- 201: Session created successfully, proceed with GET requests to monitor status
- 422: Invalid address components, check error details
- 429: Rate limit exceeded, implement exponential backoff
Important Notes
- The session token is part of the URL path for all requests after creation
- The session token is required for all subsequent requests
- The session token is valid for 30 minutes of inactivity
- Rate limits apply to all requests
Example Usage
POST /sessions
{
"street1": "29090 Tiffany Drive E",
"city": "Southfield",
"state": "MI",
"zip": "48034"
}
Authorizations
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Body
The street address of the service location.
"29090 Tiffany Drive E"
The two-letter state abbreviation of the service location.
AL
, AK
, AZ
, AR
, CA
, CO
, CT
, DE
, FL
, GA
, HI
, ID
, IL
, IN
, IA
, KS
, KY
, LA
, ME
, MD
, MA
, MI
, MN
, MS
, MO
, MT
, NE
, NV
, NH
, NJ
, NM
, NY
, NC
, ND
, OH
, OK
, OR
, PA
, PR
, RI
, SC
, SD
, TN
, TX
, UT
, VT
, VA
, WA
, WV
, WI
, WY
"MI"
The ZIP code of the service location in 12345 or 12345-6789 format.
48034
The unit, apartment, or suite number of the service location.
"A2"
The city of the service location.
"Southfield"
A unique identifier for the campaign. This is used to track the source of the session in your internal system.
"1iYyMxsnTy87tFOvukTi7V"
Response
A message returned by the API. Includes a human-readable message about the status of the request.
"What happened in the most recent request."
A status code summarizing the outcome of this response.
- ok: Request was successful
- warning: Request was processed but with some issues
- error: Request failed
ok
, warning
, error
"ok"
Metadata about the session. Can be used to track the status of the session, time since creation, and time since last update.
Was this page helpful?