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
During session creation, Hum:
- Validates and normalizes the address
- Geocodes the location
- Identifies available service providers
- Gathers plan and pricing information
Response Handling
- 201: Session created successfully with available provider results in
data - 422: Invalid address components, check error details
- 429: Rate limit exceeded; retry after the delay in
Retry-After - 503: Address validation is temporarily unavailable; retry after the delay in
Retry-After
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
- Sessions remain open until they are closed with DELETE
- 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"
}
Authorizations
Bearer token authentication using API tokens.
Include the token in the Authorization header as: Authorization: Bearer <token>
Obtain tokens from your Hum representative or contact support@letshum.com. There is no self-serve API key dashboard.
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."
An informational summary returned in API response bodies: ok for successful responses, warning for standard request errors, and error for endpoint-specific failures. Integrations must use the HTTP status code, not request_status, to determine whether a request succeeded.
ok, warning, error "ok"
Session metadata, including normalized input values, formatted service address, session status, and the Hum data set used for the response.