Deprecated features

October, 2024

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 an API usage pattern that has the potential to introduce performance issues.

The rollout of the change is planned in phases:

• Newly registered applications: The &count=false behavior will apply to collection queries made by all OAuth applications registered after Oct 13, 2024. It means developers of new Outreach API integrations have to add an explicit &count=true parameter to the collection queries in case their service expects count: ... value in response meta section. Read Counting resources for more information and examples.
• Existing applications: There will be a grace period of 3 months after we send email with notification about the upcoming change in default behavior. Developers of existing Outreach API integrations are asked to review the requirements or the implementation and append an explicit &count=true parameter to the collection queries where the count: ... value in response meta section is expected. We tentatively schedule the deprecation to become effective for existing applications on Feb 12th, 2025.

GET https://api.outreach.io/api/v2/accounts?filter[id]=0

{
  data: [],
  meta: {
    count: 0,
    count_truncated: false
  }
}

{
  data: [],
  meta: {
    count: null
  }
}

March, 2024

Outreach is committed to providing our customers with the best possible experience using our APIs. To that end, we want to inform you about an important update regarding our Audit Log API services.

Deprecation of Current Audit API: As part of our ongoing efforts to improve and update our services, the current Audit API will be officially deprecated in September, 2024. We encourage all our users to begin planning for this transition to ensure a seamless experience.

Introduction of New Audit Log API (Beta): We are introducing a new Audit Log API, which is in Beta. This next-generation API is designed with enhanced features, improved performance, and greater scalability to meet the evolving needs of our customers.

Key Dates:

• Today - Beta Release of New Audit Log API available now for early access and testing.
• September 2024 - Deprecation of current Audit Log API.

For detailed information about the new API, including documentation and support resources, please visit our Developer Portal. If you have any additional question, please contact the team at product-feedback@outreach.io.

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:

# 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:

# 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

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

Before:

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:

# 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 allowed 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:

# 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:

# 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:

# 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:

# 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)'