Clients

Clients belong to a team. You can list clients across every team you belong to, or only the current team, and you can create, update, retrieve, and archive them.

A successful read or write wraps the client in data. List responses use the same wrapper. See Pagination.

The client model

Properties

Name
id
Type
integer
Description
Unique identifier for the client.
Name
team_id
Type
integer
Description
Team that owns the client.
Name
first_name
Type
string
Description
First name.
Name
middle_name
Type
string
Description
Middle name.
Name
last_name
Type
string
Description
Last name.
Name
suffix
Type
string
Description
Name suffix.
Name
full_name
Type
string
Description
First, middle, and last name, plus the suffix when present.
Name
ssn_masked
Type
string
Description
Masked Social Security number. The API never returns the raw ssn.
Name
date_of_birth
Type
date
Description
Date of birth in YYYY-MM-DD format, or null.
Name
phone_number
Type
string
Description
Phone number.
Name
text_authorization
Type
boolean
Description
Whether the client authorized text messages.
Name
text_authorization_at
Type
date
Description
Date text authorization was recorded, in YYYY-MM-DD format.
Name
text_authorization_by
Type
string
Description
Who recorded text authorization.
Name
email
Type
string
Description
Email address.
Name
contact_preference
Type
string
Description
Phone, Email, or Text.
Name
relationship
Type
string
Description
Self, Spouse, Child, Domestic Partner, Parent, Relative, Employee, or Other.
Name
marital_status
Type
string
Description
Single, Engaged, Married, Domestic Partner, Separated, Divorced, or Widowed.
Name
gender
Type
string
Description
Male or Female.
Name
education
Type
string
Description
High School, Some College, Associates, Bachelor, Masters, Doctorate, or Medical.
Name
occupation
Type
string
Description
Occupation.
Name
agency_zoom_lead_source_id
Type
string
Description
AgencyZoom lead source id. Creating a client with lead_source on an AgencyZoom team sets this to 000000.
Name
agency_zoom_lead_source
Type
string
Description
AgencyZoom lead source label.
Name
other_lead_source
Type
string
Description
Lead source stored from the lead_source write field.
Name
hawksoft_client_id
Type
string
Description
HawkSoft client id, when the client is linked.
Name
created_at
Type
timestamp
Description
When the client was created.
Name
updated_at
Type
timestamp
Description
When the client was last updated. Lists are ordered by this field, newest first.

GET/api/clients

List all clients

Returns every matching client. There is no limit parameter. By default the list includes clients on every team the user belongs to.

Optional attributes

Name
email
Type
string
Description
Exact email match. Ignored when query is present.
Name
query
Type
string
Description
Case-insensitive match against first name, middle name, last name, full name, email, or phone number.
Name
only_current_team
Type
boolean
Description
When truthy, limit the list to the user's current team. Defaults to all of the user's teams.
Name
sortBy
Type
string
Description
Sort field. The only accepted value is updated_at, which is also the default.

Request

GET

/api/clients

curl -G https://app.riskadvisor.insure/api/clients \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -d only_current_team=1 \
  -d query=Frank

Response

{
  "data": [
    {
      "id": 42,
      "team_id": 3,
      "first_name": "Frank",
      "middle_name": null,
      "last_name": "McCallister",
      "suffix": null,
      "full_name": "Frank McCallister",
      "email": "[email protected]",
      "phone_number": "1-800-876-5309",
      "contact_preference": "Email",
      "date_of_birth": "1980-01-15"
    }
  ]
}

POST/api/clients

Create a client

Creates a client on the user's current team.

lead_source is stored as other_lead_source. When the current team has AgencyZoom, agency_zoom_lead_source_id is also set to 000000.

date_of_birth is parsed and stored as YYYY-MM-DD. An unparseable value is stored as null and does not fail the request.

Required attributes

Name
first_name
Type
string
Description
First name. Maximum 255 characters.
Name
last_name
Type
string
Description
Last name. Maximum 255 characters.
Name
phone_number
Type
string
Description
Phone number. Maximum 255 characters.
Name
email
Type
string
Description
Email address. Maximum 255 characters.

Optional attributes

Name
middle_name
Type
string
Description
Middle name.
Name
suffix
Type
string
Description
Name suffix.
Name
date_of_birth
Type
string
Description
Date of birth. YYYY-MM-DD is the preferred format.
Name
contact_preference
Type
string
Description
Phone, Email, or Text.
Name
relationship
Type
string
Description
See the client model.
Name
marital_status
Type
string
Description
See the client model.
Name
gender
Type
string
Description
Male or Female.
Name
education
Type
string
Description
See the client model.
Name
occupation
Type
string
Description
Occupation.
Name
ssn
Type
string
Description
Social Security number, 123-45-6789 or 123456789. The response includes ssn_masked, not this value.
Name
lead_source
Type
string
Description
Stored as other_lead_source.

Request

POST

/api/clients

curl https://app.riskadvisor.insure/api/clients \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Frank","last_name":"McCallister","phone_number":"1-800-876-5309","email":"[email protected]","contact_preference":"Email"}'

Response

{
  "data": {
    "id": 42,
    "team_id": 3,
    "first_name": "Frank",
    "last_name": "McCallister",
    "email": "[email protected]",
    "phone_number": "1-800-876-5309",
    "contact_preference": "Email",
    "other_lead_source": null
  }
}

GET/api/clients/:id

Retrieve a client

Returns one client when the authenticated user is allowed to view it. :id is the integer client id.

Request

GET

/api/clients/42

curl https://app.riskadvisor.insure/api/clients/42 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response

{
  "data": {
    "id": 42,
    "first_name": "Frank",
    "last_name": "McCallister",
    "email": "[email protected]",
    "phone_number": "1-800-876-5309"
  }
}

PUT/api/clients/:id

Update a client

Updates the fields you send. Omitted fields stay unchanged. The accepted fields are the same as create, and every field is optional on update.

lead_source follows the same AgencyZoom rule as create.

Request

PUT

/api/clients/42

curl -X PUT https://app.riskadvisor.insure/api/clients/42 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"1-800-555-1212"}'

Response

{
  "data": {
    "id": 42,
    "first_name": "Frank",
    "last_name": "McCallister",
    "phone_number": "1-800-555-1212",
    "email": "[email protected]"
  }
}

DELETE/api/clients/:id

Archive a client

Archives the client and related risk profiles. This does not return the client object.

Request

DELETE

/api/clients/42

curl -X DELETE https://app.riskadvisor.insure/api/clients/42 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Response

{
  "message": "Client and related RiskProfiles archived successfully."
}