Skip to main content

Read Your Generated Plays Through the API

Pull each contact's generated plays (email text, subject and sequence steps) out of Evergrowth and into your own sequencer

How to read the plays Evergrowth generated for your contacts back out through the API, so you can push them into your own email sequencer.

This guide follows on from the Evergrowth Inbound Integration Guide, which covers workflow/init: pushing accounts and contacts in and starting a workflow. Here you read the results back.

What this does

Two read calls are available on the same host and with the same API token you use for workflow/init:

  • Contact search: GET /api/company/{company_uuid}/contact/search. Returns your contacts with their plays.

  • Account search: GET /api/company/{company_uuid}/account/search. Returns your accounts.

Both calls read your own company only. A token cannot read another company.

Before you start

  • Your API token. The same bearer token starting with egt_ that you use for workflow/init.

  • Your company UUID. Looks like CO followed by a string of characters. It goes in the URL and must match the company your token is bound to.

  • Read access on your token. Ask your Evergrowth contact to switch on contact search and account search for your token. Without them the calls return 403.

How it works

  1. Call POST /api/workflow/init as before. Store contact.id from the response, and store the time you made the call (your trigger time).

  2. Wait. Plays are generated asynchronously, typically within a few minutes. Check every 15 to 30 minutes, not more often.

  3. Read the plays with contact search. Use GET, send up to 50 contact ids in one call, and keep perPage at 100 or less.

Example request

curl -G "https://data-hub.evergrowth.com/api/company/CO_your_company_uuid/contact/search" \   -H "Authorization: Bearer egt_your_token_here" \   -H "Accept: application/json" \   --data-urlencode "ids[]=CONTACT_ID_FROM_INIT" \   --data-urlencode "ids[]=ANOTHER_CONTACT_ID" \   --data-urlencode "hasPlays[]=generated" \   --data-urlencode "perPage=100"

Always use https.

What you get back

Your contacts are listed in data. Each contact has a plays object, keyed by play id. Trimmed example (other contact fields left out):

{   "data": [{     "id": "CONTACT_ID",     "plays": {       "163": {         "playId": 163,         "name": "Account follow-up",         "subjectLine": "Following up on Fernway, next step",         "generatedPlay": "Hi Maya, ...",         "status": "generated",         "updatedAt": "2026-11-16T07:20:25.000000Z",         "sequences": []       }     }   }],   "meta": { "current_page": 1, "per_page": 100, "total": 1 } }

The contact object has many more fields (name, account, email, phone and so on). Use only the ones you need.

Is a play ready?

A play is ready when both of these are true:

  • status is generated, and

  • updatedAt is later than your trigger time for that contact.

Check updatedAt every time. If you run the workflow again for a contact, the API returns the old play, with the old updatedAt, until the new play replaces it.

Plays with several steps (sequences)

  • The text of each step is in sequences, one text per step, in step order (step 1 first).

  • generatedPlay is null for these plays.

  • subjectLine is the subject for step 1 only, and it can be empty. Steps 2 and later have no subject line.

  • If a step has no text, its entry in sequences is an empty string. Check status before you use a play.

What to plan around

  • No progress status. There is no queued or in progress status. A play appears only when it is done.

  • Some plays never appear. A play that does not apply to the contact (for example, the contact's role does not match the play's targeting) is not returned. If nothing appears after about 30 minutes, treat the contact as not applicable.

  • No play type. The response does not say whether a play is an email or something else, such as a call script. Keep your own table of playId values and what each one is, and use it to decide which plays go into your sequencer.

  • No sequencer ids. Map each playId to your own sequence.

Filter values for hasPlays

You can send hasPlays[] more than once. Upper and lower case are both accepted. Allowed values:

  • generated: the play is generated.

  • not_applicable: the play does not apply to the contact.

  • failed: the play failed.

  • none: the contact has no plays.

Any other value returns 422.

Response codes

  • 200, success: read data and meta.

  • 401, missing or invalid token: check the Authorization header.

  • 403, the token may not do this: the company UUID in the URL is wrong, or the read calls are not switched on for your token. Ask your Evergrowth contact.

  • 422, invalid request: read the message. A typical cause is a hasPlays value that is not in the list above.

  • 429, too many requests: wait the number of seconds in the Retry-After header, then try again.

Limits

  • 60 calls per minute, counted per company and shared with workflow/init. Heavy polling can block your pushes, so check every 15 to 30 minutes.

  • Up to 50 contact ids per call. Use perPage of 100 or less (the default is 15), and page through with page=2, page=3 and so on.

  • The page links in the response may start with http://. Use https:// yourself.

  • Reading a single contact by id (/api/contact/{id}) is not available. Use contact search with ids[] instead.

  • Account search uses the same token, the same limits and the same 60 calls per minute.

Keep your token secret

With read access, your token can read every contact in your workspace, including emails, phone numbers and notes. Treat it like a password.

  • Store it in a secret manager. Never put it in code, Slack, email or a ticket.

  • If it leaks, or you think it might have, tell your Evergrowth contact straight away. We revoke it and issue a new one.

New fields

We may add fields to the response over time. Ignore any field you do not recognise rather than failing on it.

Support

For read access on your token, your company UUID, or help mapping plays to your sequences, contact your Evergrowth representative.

Did this answer your question?