Common tasks

Each recipe below is complete: the calls, in order, with the fields that matter. All of them need an API key with the scopes shown; see Authentication.

Add a sign-up as a contactCopy Anchor Link

Scopes: contacts:write (and leads:write if you create the company too).

When someone signs up on your site, create them as a contact. If the address already exists you get 409; find the existing contact by email and update that one instead.

const headers = { Authorization: `Bearer ${process.env.PEDIBEE_API_KEY}`, 'Content-Type': 'application/json' };
const base = 'https://api.pedibee.com/api/v1';

const res = await fetch(`${base}/contacts`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ email: user.email, name: user.name, customFields: { plan: user.plan } }),
});
if (res.status === 409) {
  const found = await fetch(`${base}/contacts?search=${encodeURIComponent(user.email)}&limit=1`, { headers });
  const { data } = await found.json();
  await fetch(`${base}/contacts/${data[0].id}`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({ customFields: { plan: user.plan } }),
  });
}

To attach them to their company, create or find the company by domain first and pass its id as leadId.

Send a welcome email when someone signs upCopy Anchor Link

Two ways, depending on how much control you want.

Send it yourself (scope email:write, the key locked to the Gmail it sends from):

curl -X POST https://api.pedibee.com/api/v1/emails \
  -H "Authorization: Bearer $PEDIBEE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "to": "jane@northwind.io", "subject": "Welcome to Acme", "text": "Hi Jane, thanks for signing up.", "signatureId": "default" }'

Let an automation do it (scope events:write): send an event and build the email, the delay and any follow-ups in Pedibee without changing your code again.

curl -X POST https://api.pedibee.com/api/v1/events \
  -H "Authorization: Bearer $PEDIBEE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "user_signed_up", "contact": { "email": "jane@northwind.io" }, "properties": { "plan": "Pro" } }'

Then in Automations, create one triggered by user_signed_up with a Send email step. The email can use {{event.plan}}. See Automations.

Keep a list in sync with your productCopy Anchor Link

Scopes: lists:write, contacts:write.

Create the list once and keep its id. Then add people as they qualify and remove them when they don't:

# add (by email: contacts that don't exist yet are created)
curl -X POST https://api.pedibee.com/api/v1/lists/$LIST_ID/contacts \
  -H "Authorization: Bearer $PEDIBEE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "emails": ["jane@northwind.io", "sam@northwind.io"] }'

# remove
curl -X DELETE https://api.pedibee.com/api/v1/lists/$LIST_ID/contacts \
  -H "Authorization: Bearer $PEDIBEE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "emails": ["sam@northwind.io"] }'

Up to 1,000 addresses per call. Your team then uses the list as the audience of a campaign or sequence.

Stop dunning when a payment succeedsCopy Anchor Link

Scope: events:write. Or connect Stripe or Paddle in Automations → Connect tools and skip the code entirely.

Send payment_failed with the invoice id, and payment_succeeded with the same id when it's paid. An automation triggered by the first and ending on the second (correlated on invoice_id) sends the reminders and stops as soon as the invoice is paid.

{ "name": "payment_failed", "contact": { "email": "jane@northwind.io" }, "properties": { "invoice_id": "in_123", "amount": 4900 } }

See Stripe and Paddle for the no-code version.

Mirror your CRM's companiesCopy Anchor Link

Scopes: leads:write, contacts:write.

Loop over your accounts and create each company with its people in one call; an existing company (same domain) is updated rather than duplicated:

{
  "companyName": "Northwind",
  "domain": "northwind.io",
  "industry": "Logistics",
  "contacts": [{ "email": "jane@northwind.io", "name": "Jane Cooper", "title": "CTO" }]
}

Store the returned ids on your side so updates go to PATCH /companies/:id.

Schedule an email for a better timeCopy Anchor Link

Scope: email:write. Add sendAt (ISO 8601 with a zone) to the send call. The email is checked at once and sent at that time from the key's Gmail. List, change or cancel what's waiting with /emails/scheduled.

RelatedCopy Anchor Link

• Errors and limits: rate limits, what each status code means.
• MCP server: the same things, done by an AI assistant on request.