API and webhooks
With the API, your CRM, webshop or print shop works directly with Trendizz: it hands over your protected customers and your exclusions, picks up the companies that responded positively and the postal campaign addresses, fetches the campaign report, and hears about events straight away through webhooks. Apex explains the setup, and tells you from the log what happened. Keys and webhooks are managed by the account's Superuser or an Administrator.
Apex's answer comes from its own knowledge and your account's log. The address is made up.
Connecting, step by step
Apex walks you through the five most common connections. The exact calls and the code samples are in the developer documentation, with a separate guide for each.
- What happens
- Apex sets out the steps: your system hands over each customer who signs up or subscribes as a protected customer, under your own ID for them; existing customers go over in batches of up to 10,000 per call; and a customer who cancels is deleted, so they can be contacted again. For a company address the domain is the right choice; for a free email provider (gmail.com, for example), the email address itself.
- Where it shows
- In the chat, in Apex's answer. You create the key in the account menu, under API and webhooks, in the Keys view.
No campaign writes to a protected customer, not even one aimed at existing customers. Those you do want to write to, for example in a repeat-purchase campaign, you load into a campaign and do not mark as protected.
- What happens
- Apex goes through the steps: the print shop's system requests an export of the campaign's addresses, only the new ones or all of them, reads a large export page by page, and after posting reports the posting date back for each company. Only an "Exported" company can move to "Posted".
- Where it shows
- In the chat, in Apex's answer.
It is the same export as in the interface, and it also appears under My exports. On every plan the test key returns sample addresses.
- What happens
- Apex explains that you add a new endpoint in the Webhooks view with the CRM's address, and tick the Positive response event. The developer receives the signing secret once, and stores it. If the CRM was unavailable for a while, fetching the positive responders fills in what was missed in the meantime.
- Where it shows
- In the chat, in Apex's answer. You add the endpoint in the account menu, under API and webhooks, in the Webhooks view.
This webhook also hands over contacts, so every delivery of it counts as an export and also appears under My exports.
- What happens
- Apex sets out the four steps: the developer reads the raw body, computes an HMAC-SHA256 signature over the timestamp and the body with the endpoint's secret, compares it with the v1 value of the Trendizz-Signature header using a constant-time comparison, and rejects any request older than 5 minutes. The code samples are in the documentation.
- Where it shows
- In the chat, in Apex's answer.
- What happens
- Apex explains that this needs a report key, named after the agency. This key only reads the account and the campaign report, as totals and broken down by day, week or month; it cannot write anything, and each key can be revoked individually. The agency uses it on your behalf in its own system or spreadsheet.
- Where it shows
- In the chat, in Apex's answer. You create the key in the account menu, under API and webhooks, in the Keys view.
The report gives counts only, no companies or contact details. The figures are the same as on the Trendizz campaign pages.
Call log and webhooks
Apex reads the call log and the webhook deliveries, tells you what happened, and opens the matching view.
- What happens
- Apex reads the call log and tells you what happened, when, with which key and on whose behalf: the successful calls and, for errors, what the error code means. On request it opens the Call log view.
- Where it shows
- In the chat, in Apex's answer, and on the right, in the Call log view of API and webhooks.
Only the key's creator can open the full response of a call that took data out; the Superuser and the Administrators, if they did not create the key, see the summary: how many companies and which fields went out.
- What happens
- Apex reads the webhook endpoints and the deliveries: what went out, when, what the endpoint answered and, if the endpoint is failing or suspended, why. It opens the Webhooks view, or a single endpoint on request.
- Where it shows
- In the chat, in Apex's answer, and on the right, in the Webhooks view.
Resending and re-enabling are done with the buttons in the Webhooks view; the account's Superuser or an Administrator can do this.
Good to know
Protected customer
No campaign writes to a protected customer. Those you want to write to, you load into a campaign; you mark as protected those you would rather leave in peace.
Test and live key
With a test key, on every plan, every call behaves as it would live, but nothing changes, and reads return sample data. The live key works on a paid plan. Keys are created by the account's Superuser and Administrators; the report key only reads the account and the campaign reports.
One limit for everyone
On every plan, 1,000 calls per company per hour, separately for the test and the live key.
Everything logged
Every call and every webhook is in the log: when, with which key, what was requested and what came back. The Superuser and the Administrators can see the details for 90 days.
Try it free.
Ask Apex. It answers in your own account, tailored to your company.