Articles in this section

See more

API Deprecation FAQ

Avatar
Aye
Updated
Follow

Purpose

The purpose of this FAQ is to provide information about the Outreach API deprecation.

Applies To

  • Outreach API

Notes

Frequently Asked Questions

Q: Why are we planning to deprecate these APIs?

A: 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. 

Q: What APIs are going to be deprecated?

A: Below is a comprehensive list of API features that will be deprecated: 

  • Sorting by relationship's attribute
  • Including related objects to the response of create or update operation
  • Filters by relationship's attribute for some of the endpoints or relations

Q: What are the suggested workarounds for migrating from these APIs?

A: We recommend the below: 

  • Sorting: Please fetch the result of your query with the relationship's attribute included and apply sorting locally in your service.
  • Includes on create/update: Please do an additional GET request.
  • Filters: Please consult the reference documentation for each relationship to see whether you can use filters like:
 filter[relationship_abc][attribute_1]=Acme, or only filter[relationship_abc][id]=1 is allowed. In the latter case you need to do two requests, first get a list of relationship IDs querying /api/v2/model_abc?filter[name]=Acme and then pass them to the original query as filter[relationship_abc][id]=1,2,3.

Q: Can you provide some code examples of the deprecated APIs?

A: Yes, we have included some examples of how you could look different before and after the deprecation of these APIs.

  • Sorting

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)'
  • Includes on create/update.

Before


curl -s -H 'Content-Type: application/vnd.api+json' -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects?include=account"   -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 'Content-Type: application/vnd.api+json' -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects"   -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

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

 

Q: Where can I find the updated API documentation?

A: All API Documentation can be found here. 

Q: What happens if the affected Apps don’t stop using deprecated APIs by the end date?

A: The identified APIs will stop working  For example, instead of getting a sorted set of values, partners will get an error message.

Q: How can I tell if I am utilizing one of these APIs?

A: If you received a communication from Outreach, you are utilizing one of the APIs that will be deprecated. If you’d like to understand which specific APIs you are using, please reach out to Platform@outreach.io 

Q: Are you planning to deprecate more APIs in the future?

A: We understand it requires resources for partners and customers to make the necessary changes to the APIs.  We will work towards not impacting our customers and partners.  However, we cannot guarantee that there will be no changes as we work towards modernizing our platform technologies to provide the innovations needed to meet our customer's needs.  Outreach will ensure partners have a grace period and support channel to support the change. 

Q: What resources is Outreach offering to make it easy for App developers to stop using the APIs that are being deprecated?

A: We will be hosting office hours with our platform product and engineering team to answer questions. We also have a dedicated resource to answer any questions at platform@outreach.io 

Q: Where can I go if I have questions or feedback?

A: Please email our Platform team (Platform@outreach.io) and they will be happy to address your questions or hop on a call to talk through any issues. 

Related articles