Skip to main content
This walkthrough sets up a two-way sync between an external CRM (HubSpot, Salesforce, Attio, or a homegrown one) and Orgo’s Contact resource. The pattern: push contacts on a schedule, then keep both sides current incrementally through webhooks. Who is this for: marketing-ops integrations that own the CRM and need to project contact data into Orgo so it can drive newsletters, event invites and audience filters. Your Api-Token must belong to a user who can manage contacts (HR or finance rights over the contact’s chapter). Tagging and newsletter subscription need organization-wide HR rights, and creating tags needs organization-wide admin rights.

Architecture in two paragraphs

Your CRM is the source of truth for contact details. Orgo is the source of truth for what that contact has done inside Orgo: events attended, payments made, contracts signed, newsletter engagement. The sync pushes contact details one way and pulls Orgo activity the other way. Both sides change day to day. Without webhooks you would poll Orgo for “what changed since yesterday”, which is slow, and contacts have no “updated since” filter to poll with. With webhooks, Orgo tells you the moment a contact is created, edited or removed. Use webhooks for the Orgo to CRM direction.

Step 1: Bulk import from the CRM to Orgo

Create one contact per CRM record with POST /api/v1/contacts. If the email already belongs to a contact or a member, the call answers 409 Conflict, so you can rerun an import safely.
Contacts take name or firstName and lastName, plus email, phone, organisation, role, town, country, gender, dateBirth, social links, company fields, customFieldValues and localCenter. The response carries the contact id, source: "MANUAL" and the read-only isNewsletterSubscribed flag. Newsletter opt-in cannot be set on create, see step 3. For thousands of contacts, parallelize with a modest cap (around 10 concurrent requests) rather than flooding the endpoint.

Conflict handling

When POST returns 409, the email already exists. Either skip it (your CRM was already in sync) or merge: look the contact up by email and update it with the fresher CRM data.
If the 409 is because the address belongs to a member, the email is not a contact at all: update the user instead, or leave it.

Step 2: Tag contacts for audience filtering

Tags label contacts for filtering and for newsletter audiences. Mirror your CRM segments as tags. A tag is created once, then attached to each contact with a profile tag:
List a contact’s tags with GET /api/v1/contacts/85/profile_tags, and find every contact with a tag using GET /api/v1/contacts?tags.tag=/api/v1/tags/14. Remove a tag from a contact by deleting the profile tag: DELETE /api/v1/profile_tags/{id}. Run tagging after the initial import. One round trip per contact-tag pair is fine up to around ten thousand contacts.

Newsletter subscription

Whether a contact receives newsletters is a flag Orgo manages, with an audit entry for every change. Set it with:
Both are GET calls and need organization-wide HR rights. Respect opt-outs: a person who unsubscribes through an email link has the flag turned off, and your sync should not turn it back on without their consent.

Step 3: Subscribe to Orgo events

Register a webhook so Orgo pushes updates as they happen:
Creating webhook subscriptions needs the Orgo administrator flag. See Handle webhooks for the receiver implementation.

Step 4: Receive and write back to the CRM

When Orgo fires a contact.updated webhook, your handler:
  1. Verifies the signature.
  2. Looks up the same contact in your CRM by email.
  3. Writes back the fields Orgo owns (newsletter opt-in, attendance, payments).
The payload shape:
previous_attributes is the diff: fields not mentioned did not change. That is enough to detect an unsubscribe without comparing against a stored snapshot.

Step 5: Catch up after downtime

If your receiver was down, look at the subscription’s recent delivery attempts:
The log lists successes and failures, with the payload of each attempt, up to 500 at a time. For each failed delivery, re-process the payload locally. Failed deliveries are retried automatically a few times (see Webhooks), so most short outages heal themselves. For a longer outage, or if you suspect you missed events, run a reconciliation pass. Contacts cannot be filtered by update time, so page through the whole collection in a stable order and compare it with your CRM:
To pick up only new contacts since your last pass, order by creation: order[dateCreated]=desc, and stop when you reach a contact you already have.

Common gotchas

Orgo deduplicates by exact email, and only when a contact has an email. If your CRM holds several records for one person under different addresses, Orgo stores them as separate contacts. Dedupe in your CRM first, or merge in Orgo before syncing (see the merge tool under Settings → Developers → Merge Records).
When a person becomes a member, a user.created webhook fires. Match it to your CRM record by email and point the record at the member. Do not assume the contact record disappears or stays; treat the email as the join key.
Check GET /api/v1/webhook_subscriptions/3/delivery_logs. Common causes: the receiver returns a non-2xx status, it takes longer than the subscription’s timeoutSeconds (30 by default), a TLS problem, or an address Orgo refuses to call (private or non-standard port). Orgo makes up to maxRetries attempts (3 by default) before giving up.
Only HR with organization-wide rights can create members, with POST /api/v1/member-register-by-admin, which sends each person a welcome email. For most CRM use cases contacts are the right primitive: promote selected ones to members through the application flow when they are ready, see Onboard a new member.

What to do next