crowd.dev

To get started, you will need the **tenant ID** and the **API key**, both of which can be obtained in the [Settings](https://app.crowd.dev/settings?activeTab=api-keys) section of the app.

API Reference

The API for contacts will allow you to find, query, and add new contacts. You will also be able to perform important operations on them such as enriching or merging.

Contact (member)

The query endpoint can be used to list your contacts (members). You can filter on most columns and attributes.

Query

Find by id

This endpoint is used to create or update a contact (member). The only required fields are:

- `username`: the username of the contact in the selected platform
- `platform`**:** the platform where the username belongs
    

For example, if you are adding a contact with username _joanreyero_ from GitHub: `{"username": "joanreyero", "platform": "github"}`.

Other important fields are:

- `emails`**:** a list of emails that belong to the contact. These will be useful for identity resolution and enrichment
- `displayName`: how the name of the contact will show on the crowd.dev UI
- `attributes`: see the section below
    

### Sending attributes

Several attributes can be sent by default

- `location`: the location of the contact
- `bio`: a biography of the contact
- `url`: a url for the contact
- `jobTitle`: a job title for the contact
    

### Checking existence

We check existence is checked by the combination of username and platform. If we detect a contact with that username and platform, we will do an update instead of creating a new contact.

### Updates

We recommend using this endpoint instead of update for performing updates, especially on `attributes`.

Create or update

This endpoint is used to enrich a member. Only members with either a GitHub identity or an email can be enriched.

If you try to enrich a member that does not have these identities, the enrichment will not go through, but you won't spend any credits.

Enrich one

Updates in members are hard updates and are not recommended. When possible, we recommend using the _Crate or Update_ endpoint. You can update members using that endpoint by identifying them by username and platform. For example, if you want to update a member with username _joanreyero_ in the platform GitHub, you can identify it by `{"username": "joanreyero", "platform": "github"}`.

Update

Delete

Get the merge suggestions that our algorithm found for the contacts in your community.

Get contacts merge suggestions

Merge two contacts. The activities and organizations of both contacts will be unioned. The information from the primary contact (in the request URL) will have priority.

Merging is currently a non-reversible operation. Use it with care!

Merge

Mark two contacts (members) as not being the same. The merge suggestions algorithm will not give suggestions for these contacts anymore.

Add to not merge

The API for organizations will allow you to find, query, and add new organizations. You will also be able to perform important operations on them such as merging.

Organization

This endpoint allows you to create or update an organization.

There are two required fields when creating an organization:

- `name`: a name for the organization
    
- `website`: the website for the organization. This is unique across your workspace
    

You can also add more information about it:

- `logo`: a URL to a logo image. It will be used in the UI as the avatar
    
- `description`: a description of the organization
    
- `location`: location information for the organization
    
- `emails`: a list of emails associated with the organization
    
- `phoneNumbers`: a list of phone numbers associated with the organization
    
- `identites`: a list of identities associated with the organization. They should have the following form:
    
    - `platform`: the platform, for example, _github_
    - `name`: the name of the identity in the platform, for example, _CrowdDotDev_
    - `url`: the URL for that identity, if applicable
        

Organizations have other fields, but we do not support populating them directly through API yet. These are populated from enrichment.

## Checking existence

Existence is checked by the `website`, and the organization's identities are in the different platforms. If there is a match, we will do an update instead of creating a new organization.

Get the merge suggestions that our algorithm found for the organizations in your community.

Get organizations merge suggestions

Merge two organizations. The activities and contacts of both contacts will be unioned. The information from the primary organization (in the request URL) will have priority.  

Merging is currently a non-reversible operation. Use it with care!

Mark two organizations as not being the same. The merge suggestions algorithm will not give suggestions for these organizations anymore.

The API for activities will allow you to find, query, and add new activities.

Activity

If we detect activities belong in the same thread or group, we will group them into conversations. Activities may have a `conversationId` field that marks the conversation to which they belong. This endpoint will allow you to retrieve a whole conversation for a given `conversationid`.

Find conversation by id

This endpoint will allow you to create or update an activity with a member.  
There are several required fields in the request body:

- `sourceId`: a unique ID for the activity at the source (for example, the ID of the message in Slack)
- `platform`: where the activity comes from (GitHub, Hubspot...)
- `type`: the type of activity (message, attended-conference)
- `timestamp`: when the activity happened
- `member`: a JSON structure with at least a `username`. You can also send any other contact columns.
    

There are other optional columns that you can send:

- `title`: a title for the activity, which will show in the UI  
    `body`: a body text for the activity, which will show in the UI  
    `url`: a URL of the activity  
    `channel`: the channel within the platform where the activity happened. For example, for GitHub this would be the repo.  
    `sourceParentId`: if the activity has a parent at the source platform, this would be the ID of the parent in the platform. For example, if the activity is a pull request comment, this field would be the ID of the pull request in GitHub.  
    `attributes`: a JSON with other attributes you would want to save.
    

### Checking existence

Existence is checked by `sourceId`, and crowd.dev will check for deduplication on our end. Deduplication for the contact is also checked based on the username of the contact on that platform.

The API for tags will allow you to find, query, and add new tags.

This endpoint allows you to create tags for contacts. The only compulsory field is the `name`, which has to be unique. You can optionally also send a list of members that will have those tags.

Create

Autocomplete

The API for tasks will allow you to find, query, and add new tasks.

Task

This endpoint allows you to create tasks related to contacts or activities, and assign them to yourself or other team members. To create a task need only one required column, `name`. You can also add:

- `status`: the status (_in-progress, done, archived, or_ `null`)
- `dueDate`: the date the task is due
- `members`: a list of contact (member) IDs that the task is related to
- `activities`: a list of activity IDs the task is related to
- `assignees`: a list of user IDs the task is related to

The API for notes will allow you to find, query, and add new notes.

Note

This endpoint allows you to create notes related to contacts. To create a note you need:

- `body`: the body of the note (supports markdown)
    
- `members`: a list of contact (member) IDs that the note is related to

Sections