Deprecated features

May, 2023

Outreach is continuously looking for ways to improve performance and give developers greater flexibility in using our APIs. In a recently conducted review, we identified three API behaviors that have the potential to introduce performance and data inconsistency issues. Since the issues resulting from these API behaviors outweigh their benefits, we have decided to deprecate these API behaviors on October 31, 2023.

The deprecation is effective immediately for any new integrations and integrations that have not used these features in the last four months. Integrations that used at least one of the deprecated features will be able to operate till October 31, 2023.

In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to deprecate the following API features:

Sorting by relationship's attribute

Please fetch the result of your query with the relationship's attribute included and apply sorting locally in your service.

Before:

Copy

Copied

# instead of sorting tasks by prospect’s name
curl -s -H "$AUTH" "$HOSTNAME/api/v2/tasks?filter[dueAt]=2023-04-10..inf&sort=prospect.firstName"

After:

Copy

Copied

# fetch tasks with prospect’s name included
curl -s -H "$AUTH" "$HOSTNAME/api/v2/tasks?filter[dueAt]=2023-04-10..inf&include=prospect&fields[prospect]=name" > tasks.json

# prepare map for sorting
jq '[.included[] | {"\(.id)":.attributes.name}] | add' tasks.json > sort_by.json

# sort tasks by prepared map
jq --slurpfile m sort_by.json '.data | sort_by($m[0]["\(.relationships.prospect.data.id)"])' tasks.json

Including related objects to the response of create or update operation

Plese replace the single POST/PATCH request with two: POST/PATCH of the main object followed by GET request for related objects.

Before:

Copy

Copied

curl -s -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects?include=account" -H 'Content-Type: application/vnd.api+json' \
     -d '{"data":{"type":"prospect","attributes":{"company":"Acme Corp.","emails":["jane@acme.com"],"firstName":"Jane","lastName":"Doe"}}}' > prospect.json

After:

Copy

Copied

# create or update the object without including related objects
curl -s -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects" -H 'Content-Type: application/vnd.api+json' \
     -d '{"data":{"type":"prospect","attributes":{"company":"Acme Corp.","emails":["jane@acme.com"],"firstName":"Jane","lastName":"Doe"}}}' > prospect.json

# get the IDs you need from the response
PROSPECT_ID=`jq .data.id prospect.json`
ACCOUNT_ID=`jq .data.relationships.account.data.id prospect.json`

# and fetch the related object directly
curl -s -H "$AUTH" "$HOSTNAME/api/v2/accounts/$ACCOUNT_ID"
# alternatively you can refetch the main object with included related objects
curl -s -H "$AUTH" -X GET "$HOSTNAME/api/v2/prospects/$PROSPECT_ID?include=account"

Filters by relationship's attribute for some of the endpoints or relations

Please consult the reference documentation for each relationship to see whether you can use filters by relationship's attributes, relationship id only, or not even that.

If filtering is alowed by id only, split the original single request to two, get ids of related object(s) in the first request and pass them to the adjusted original request.

Before:

Copy

Copied

# instead of sequence.name filter in 2 steps by sequence.id as that is supported
curl -s -H "$AUTH" "$HOSTNAME/api/v2/mailings?filter[sequence][name]=ABCD"

After:

Copy

Copied

# fetch IDs of sequences first (no need to fetch any attributes)
curl -s -H "$AUTH" "$HOSTNAME/api/v2/sequences?filter[name]=ABCD&fields[sequence]=" > sequences.json
SEQ_IDS=`jq -r '[.data[] | .id] | join(",")' sequences.json`

# then fetch the objects by IDs of related objects
curl -s -H "$AUTH" "$HOSTNAME/api/v2/mailings?filter[sequence][id]=$SEQ_IDS"

If filtering by the relationship is not allowed, query the related object and include the original one. This workaround applies if you want to obtain parent entity (e.g. account) filtered by child entity (e.g. prospect). Also in the specific case of accounts/prospects you might want to exclude unnamed accounts from the response as those are not returned by /api/v2/accounts endpoint by default.

Before:

Copy

Copied

# instead of filtering accounts by prospect filter prospects and include accounts as that is supported
curl -s -H "$AUTH" "$HOSTNAME/api/v2/accounts?filter[prospects][updatedAt]=2023-04-14..inf"

After:

Copy

Copied

# fetch IDs of prospects only (no need to fetch any attributes as we want accounts)
# in this case we should exclude unnamed accounts which are not returned by original query
curl -s -H "$AUTH" "$HOSTNAME/api/v2/prospects?filter[updatedAt]=2023-04-14..inf&fields[prospect]=&include=account" | jq '.included[] | select(.attributes.named)'