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 withPOST /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.
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
WhenPOST 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.
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: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: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:Step 4: Receive and write back to the CRM
When Orgo fires acontact.updated webhook, your handler:
- Verifies the signature.
- Looks up the same contact in your CRM by email.
- Writes back the fields Orgo owns (newsletter opt-in, attendance, payments).
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:order[dateCreated]=desc, and stop when you reach a contact you already have.
Common gotchas
My import is creating duplicate contacts
My import is creating duplicate contacts
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).
A contact became a member mid-sync and my CRM has stale state
A contact became a member mid-sync and my CRM has stale state
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.Webhook deliveries are failing silently
Webhook deliveries are failing silently
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.Can I import members directly instead of contacts?
Can I import members directly instead of contacts?
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
- Handle webhooks: the receiver implementation in detail
- Send a newsletter campaign: once contacts are synced, target them
- Onboard a new member: promote a contact into a full member

