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
Provide address using one of: (street1 and zip), (street1, city, and state), or (street1, city, and zip). State is optional when zip is present.
POST /sessions
{
"street1": "29090 Tiffany Drive E",
"zip": "48034"
}
Or with city and state, or street+city+zip (no state):
POST /sessions
{
"street1": "29090 Tiffany Drive E",
"city": "Southfield",
"state": "MI",
"zip": "48034"
}
Documentation Index
Fetch the complete documentation index at: https://docs.letshum.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Bearer token authentication using API tokens.
Include the token in the Authorization header as: Authorization: Bearer <token>
Obtain tokens through your Hum API account dashboard or contact support@letshum.com for access.
Body
Service address for the session. Provide one of: street1 and zip; street1, city, and state; or street1, city, and zip. State is optional when zip is present. street2, latitude, longitude, and campaign_id are optional.
Service address. Provide one of: street1 and zip; street1, city, and state; or street1, city, and zip. State is optional when zip is present.
The street address of the service location.
1 - 100"29090 Tiffany Drive E"
The unit, apartment, or suite number of the service location.
1 - 50"A2"
The city of the service location. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
1 - 50"Southfield"
The two-letter state abbreviation. Required when using the (street1, city, state) combination; optional when providing street1 and zip.
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 ^[A-Z]{2}$"MI"
The ZIP code in 12345 or 12345-6789 format. Required when using the (street1, zip) combination; optional when providing street1, city, and state.
^\d{5}(-\d{4})?$48034
The latitude of the service address.
42.501721339274
The longitude of the service address.
-83.286263465881
A unique identifier for the campaign. This is used to track the source of the session in your internal system.
1 - 100"1iYyMxsnTy87tFOvukTi7V"
Response
Successful session creation.
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.