Sessions

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

Synchronous Processing

You can optionally specify certain agents to run synchronously during the request by providing the sync parameter:

Include agent names in an array: ["geocode", "internet"]
Available agents: geocode, internet
Synchronous requests may take longer to complete but return more complete initial data
Use this for time-sensitive operations where immediate results are required
AI agents (ie, plans, pricing, etc) are run asynchronously by default and cannot be run synchronously
Updates to the plans and pricing components will be available asynchronously after each AI agent completes processing

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",
  "sync": ["geocode"]
}

POST

sessions

curl --request POST \
  --url https://api-sandbox.letshum.com/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "street1": "29090 Tiffany Drive E",
  "street2": "A2",
  "city": "Southfield",
  "state": "MI",
  "zip": 48034,
  "campaign_id": "1iYyMxsnTy87tFOvukTi7V",
  "sync": [
    "geocode",
    "internet"
  ]
}'

{
  "message": "What happened in the most recent request.",
  "request_status": "ok",
  "data": {
    "session_token": "Xxjljd2CQgobOvPR3X6Lat"
  },
  "meta": {
    "session_token": "Xxjljd2CQgobOvPR3X6Lat",
    "session_status": "open",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "session_params": {
      "street1": "29090 Tiffany Drive E",
      "street2": "A2",
      "city": "Southfield",
      "state": "MI",
      "zip": 48034,
      "campaign_id": "1iYyMxsnTy87tFOvukTi7V",
      "sync": [
        "geocode",
        "internet"
      ]
    },
    "service_address": {
      "normalized": "29090 TIFFANY DR E, SOUTHFIELD, MI, 48034",
      "latitude": 42.501721339274,
      "longitude": -83.286263465881,
      "street_range": "29000-29098",
      "street": "29090 Tiffany Drive E",
      "city": "Southfield",
      "state": "MI",
      "zip": 48034
    },
    "created_at": "2024-09-20T23:13:31.179Z",
    "updated_at": "2024-09-20T23:13:31.179Z",
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "v.1005"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

A JSON object that contains the service address components for the session.

street1

string

required

The street address of the service location.

Example:

"29090 Tiffany Drive E"

zip

string

required

The ZIP code of the service location in 12345 or 12345-6789 format.

Example:

48034

street2

string

The unit, apartment, or suite number of the service location.

Example:

"A2"

city

string

The city of the service location.

Example:

"Southfield"

state

enum<string>

The two-letter state abbreviation of the service location.

Available options:

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

Example:

"MI"

campaign_id

string

A unique identifier for the campaign. This is used to track the source of the session in your internal system.

Example:

"1iYyMxsnTy87tFOvukTi7V"

sync

enum<string>[]

An array of agent names to run synchronously. If provided, these agents will execute during the request instead of asynchronously. Available agents are "geocode" and "internet".

Available options:

geocode,

internet

Example:

["geocode", "internet"]

Response

201

application/json

Successful session creation.

message

string

required

A message returned by the API. Includes a human-readable message about the status of the request.

Example:

"What happened in the most recent request."

request_status

enum<string>

required

A status code summarizing the outcome of this response.

ok: Request was successful
warning: Request was processed but with some issues
error: Request failed

Available options:

ok,

warning,

error

Example:

"ok"

data

object

required

meta

object

required

Metadata about the session. Can be used to track the status of the session, time since creation, and time since last update.

meta.created_at

string

required

A timestamp in ISO 8601 format.

Example:

"2024-09-20T23:13:31.179Z"

meta.updated_at

string

required

A timestamp in ISO 8601 format.

Example:

"2024-09-20T23:13:31.179Z"

meta.responded_at

string

required

A timestamp in ISO 8601 format.

Example:

"2024-09-20T23:13:31.179Z"

meta.session_token

string

The session token provided by the Hum API. Used to connect the response to the session in the client system.

Example:

"Xxjljd2CQgobOvPR3X6Lat"

meta.session_status

enum<string>

The status of the session.

Available options:

open,

closed

Example:

"open"

meta.agent_status

object

meta.session_params

object

meta.session_params.street1

string

required

The street address of the service location.

Example:

"29090 Tiffany Drive E"

meta.session_params.zip

string

required

The ZIP code of the service location in 12345 or 12345-6789 format.

Example:

48034

meta.session_params.street2

string

The unit, apartment, or suite number of the service location.

Example:

"A2"

meta.session_params.city

string

The city of the service location.

Example:

"Southfield"

meta.session_params.state

enum<string>

The two-letter state abbreviation of the service location.

Available options:

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

Example:

"MI"

meta.session_params.campaign_id

string

A unique identifier for the campaign. This is used to track the source of the session in your internal system.

Example:

"1iYyMxsnTy87tFOvukTi7V"

meta.session_params.sync

enum<string>[]

An array of agent names to run synchronously. If provided, these agents will execute during the request instead of asynchronously. Available agents are "geocode" and "internet".

Available options:

geocode,

internet

Example:

["geocode", "internet"]

meta.service_address

object

The service address components for the session.

meta.hum_data_set

string

The version of the Hum data set used to generate the response. This version may change as the data set is updated.

Example:

"v.1005"

Was this page helpful?

Get Session Status

curl --request POST \
  --url https://api-sandbox.letshum.com/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "street1": "29090 Tiffany Drive E",
  "street2": "A2",
  "city": "Southfield",
  "state": "MI",
  "zip": 48034,
  "campaign_id": "1iYyMxsnTy87tFOvukTi7V",
  "sync": [
    "geocode",
    "internet"
  ]
}'

{
  "message": "What happened in the most recent request.",
  "request_status": "ok",
  "data": {
    "session_token": "Xxjljd2CQgobOvPR3X6Lat"
  },
  "meta": {
    "session_token": "Xxjljd2CQgobOvPR3X6Lat",
    "session_status": "open",
    "agent_status": {
      "geocoding": "matched",
      "internet": "matched",
      "checkout": "pending"
    },
    "session_params": {
      "street1": "29090 Tiffany Drive E",
      "street2": "A2",
      "city": "Southfield",
      "state": "MI",
      "zip": 48034,
      "campaign_id": "1iYyMxsnTy87tFOvukTi7V",
      "sync": [
        "geocode",
        "internet"
      ]
    },
    "service_address": {
      "normalized": "29090 TIFFANY DR E, SOUTHFIELD, MI, 48034",
      "latitude": 42.501721339274,
      "longitude": -83.286263465881,
      "street_range": "29000-29098",
      "street": "29090 Tiffany Drive E",
      "city": "Southfield",
      "state": "MI",
      "zip": 48034
    },
    "created_at": "2024-09-20T23:13:31.179Z",
    "updated_at": "2024-09-20T23:13:31.179Z",
    "responded_at": "2024-09-20T23:13:31.179Z",
    "hum_data_set": "v.1005"
  }
}

Sessions

Service Availability

Health Check

Create New Session

Request Flow

Processing

Synchronous Processing

Response Handling

Important Notes

Example Usage

Authorizations

Body

Response