Skip to main content

Make your first request

This example reads one contact. Use an identifier and scope that your application is permitted to access. If you have leads-only credentials, use the lead capture recipe instead.

1. Request a token​

Set the following values in your shell from your issued credentials. Supply secrets through your usual secure configuration mechanism rather than committing them to a script.

# AUTH_URL is the complete token endpoint supplied to you.
# CLIENT_ID, CLIENT_SECRET and SCOPES are your application's values.
curl --request POST "$AUTH_URL" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "scope=$SCOPES"

The response contains access_token, token_type and expires_in. Cache the token securely and request another before it expires. OAuth explained covers the complete flow.

2. Read a record​

Use the issued API base URL without a trailing slash. It should not already end in /jsonapi when using the paths in this guide.

curl --fail-with-body --globoff \
  "$API_BASE_URL/jsonapi/contacts/$CONTACT_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "UserId: $ADVISER_CONTACT_ID" \
  --header 'Accept: application/vnd.api+json'

3. Understand the response​

The result is a JSON:API document. The primary record lives in data; business fields are in data.attributes. Related records are represented through relationships and may be returned in included when requested.

A 401 normally means authentication needs attention. A 403 can indicate scopes, adviser context or data permissions. Do not treat an empty search result as proof a record does not exist. See troubleshooting.