Common API calls

Create / update (upsert) a member

To a) create or b) update a member when the id is not known, send a POST request to the /{workspace_id}/members endpoint including an identity that will be used to locate the member:

// POST https://app.orbit.love/api/v1/{workspace_id}/members

{
  "name": "Patrick Woods",
  "tags_to_add": "Founder, Fencer",
  "identity": {
    "source": "email",
    "email": "[email protected]"
  }
}

Here we specify that the member's name is Patrick Woods and they have an email identity with an email of [email protected].

• If no member with this email exists, then
  • a new member will be created with the given attributes
• If a member with the email already exists, then
  • the existing member will be updated with the attributes sent

Note: Passing an identity is optional. If you don't pass one, a new member will be created every time. If you need to, you can always merge that member with another inside of Orbit.

Update a member when an ID is known

If you already know the ID or slug of a member, you can update them directly. Passing an identity is not required and will be ignored if present.

// POST https://app.orbit.love/api/v1/{workspace_id}/members/{member_id}

{
  "name": "Patrick Woods",
  "location": "San Francisco",
  "tags_to_add": "Founder, Fencer"
}

Create an activity

This is an example of how you might track an Eventbrite registration as an activity in Orbit.

There are two endpoints you can use depending on whether:

• A: you know the slug or the Orbit id of the member you're creating an activity for
• B: you don't know the id or slug but have another piece of identifying information from another system like a GitHub handle, Twitter handle, email address, or external ID from your product.

A: If you do know the member's id or slug:

// POST https://app.orbit.love/api/v1/{workspace_id}/members/{member_id}/activities

{
  "description": "May 17 - Getting Started with the Orbit Model",
  "link": "https://orbit-event.eventbrite.com/",
  "link_text": "See the event",
  "title": "Orbit Meetup Registration",
  "activity_type_key": "eventbrite:registration",
  "key": "registration-1827374",
  "occurred_at": "2020-05-10T00:00:00Z"
}

Note: The member_id parameter is present in the path. That's how the activity knows which member to attach to.

Note: occurred_at should be a valid ISO 8601 date. All times are UTC.

B: If you don't know the member's id or slug:

// POST https://app.orbit.love/api/v1/{workspace_id}/activities

{
  "description": "May 17 - Getting Started with the Orbit Model",
  "link": "https://orbit-event.eventbrite.com/",
  "link_text": "See the event",
  "title": "Orbit Meetup Registration",
  "activity_type_key": "eventbrite:registration",
  "key": "registration-1827374",
  "occurred_at": "2020-05-10T00:00:00Z",
  "identity": {
    "source": "email",
    "email": "[email protected]"
  }
}

There is no member_id in the path in this version, but it's the identity in the body that is used to find the member to attach the activity to.

In this example:

• if a member exists with an email identity of "[email protected]" then
  • the activity will be attached to that existing member
• if no member exists with an email identity of "[email protected]" then
  • a new member will be created
  • the "[email protected]" email identity will be associated with them
  • the activity will be attached to that new member

This endpoint is useful when you are integrating a system that has no knowledge of Orbit or their user's Orbit member ID, but you do have an identifier from that system. Without this endpoint, you'd need to get the member ID first, create it if it didn't exist, and then pass the member ID when creating the activity. This endpoint provides a shortcut to do all of that in one call and is the most common one used for integrations.

📘

Without Passing An Identity

If you call this endpoint without passing an identity, the call will succeed, and a new member will be created each time. You can always merge these members with others if necessary inside the Orbit application.

The identity isn't limited to email but can be other sources like GitHub, Twitter, Discourse, LinkedIn, DEV, as well as custom sources. See the introduction to the identities concept above for more information.

Update member attributes while creating an activity

Commonly, you might want to update a member attribute at the same time as creating an activity. For example, to add an attendee tag to a member who records an event registration activity.

To accomplish this, we can include a member object inside of the JSON body.

// POST https://app.orbit.love/api/v1/{workspace_id}/activities

{
  "description": "May 17 - Getting Started with the Orbit Model",
  "link": "https://orbit-event.eventbrite.com/",
  "link_text": "See the event",
  "title": "Orbit Meetup Registration",
  "activity_type_key": "eventbrite:registration",
  "key": "registration-1827374",
  "occurred_at": "2020-05-10T00:00:00Z",
  "member": {
    "tags_to_add": "Attendee"
  },
  "identity": {
    "source": "email",
    "email": "[email protected]"
  }
}

Note: This works with both versions of creating an activity, where the member_id is provided or where an identity object is used in the body to find or create the member.

Find a member

To look up a member based on an email address, GitHub handle, or Twitter handle, use the find endpoint. Here are a few examples:

# find a member who is patrickjwoods on github

https://app.orbit.love/api/v1/orbit/members/find?source=github&username=patrickjwoods

# find a member with an email address of [email protected]

https://app.orbit.love/api/v1/orbit/members/find?source=email&[email protected]

Valid query params are the same as identity attributes and include:

• source: Set to github, twitter, email, discourse or the source of any identities you've manually created
• source_host: Set to the source host - generally only needed for Discourse
• username: The username at the source
• uid: The uid at the source
• email: The email address when the source is email

Provide just one of { username | uid | email } according to the source and the type of value that you have. For a source of twitter and github you would provide username. For an email source you should always provide an "email".