Purpose
The purpose of this article is to provide information to Outreach Admins or Users regarding API support for the Multi-User Assignment feature.
Intended Audience
- Outreach Users
- Outreach Admins
You can learn more about the feature in Multi-User Assignment Overview and enable the feature for your organization by following the steps detailed in Getting Started with Multi-User Assignment.
API List
Accounts
To assign multiple users to an account, use the assignedUsers relationship via the accounts API v2 endpoint.
Get Account with Assigned Users
Assigned users are returned via the assignedUsers relationship on the account. The field is an array. The id field maps to the user id on the https://api.outreach.io/api/v2/users/{:id} endpoint.
Request example:
GET https://api.outreach.io/api/v2/accounts/{:id}
Success response code 200
Response example:
|
{ "data": { "type": "account", "id": 79, "attributes": { ... }, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 }, { "type": "user", "id": 22 }, { "type": "user", "id": 26 } ], "links": { "related": "https://api.outreach.io/api/v2/users?filter%5Baccount%5D%5Bid%5D=79" }, "meta": { "count": 4 } }, "owner": { "data": { "type": "user", "id": 26 } }, ... }, "links": { "self": "https://api.outreach.io/api/v2/accounts/79" } } } |
Create Account with Assigned Users
To add assigned users while an account is being created, use the assignedUsers relationship for the account. One of the users will be assigned as the owner as a side effect of setting the assignedUsers.
POST https://api.outreach.io/api/v2/accounts
Success response code 201
Request payload:
|
{ "data": { "type": "account", "attributes": { "name": "Assignment Account" }, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Update Assigned Users for Account
Replace All Assigned Users
To replace all users that are currently assigned to the account, use the assignedUsers relationship for the account. One of the users will be assigned as the owner as a side effect of setting the assignedUsers.
PATCH https://api.outreach.io/api/v2/accounts/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "account", "id": 79, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Remove All Assigned Users
To remove all assigned users for an account, use the assignedUsers relationship for the account and set it to an empty array. The owner of the account will also be removed as a side effect.
PATCH https://api.outreach.io/api/v2/accounts/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "account", "id": 79, "relationships": { "assignedUsers": { "data": [] } } } } |
Prospects
Get Prospect with Assigned Users
Request example:
GET https://api.outreach.io/api/v2/prospects/{:id}
Success response code 200
Response example:
|
{ "data": { "type": "prospect", "id": 79, "attributes": { ... }, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 }, { "type": "user", "id": 22 }, { "type": "user", "id": 26 } ], "links": { "related": "https://api.outreach.io/api/v2/users?filter%prospect%5D%5Bid%5D=79" }, "meta": { "count": 4 } }, "owner": { "data": { "type": "user", "id": 26 } }, ... }, "links": { "self": "https://api.outreach.io/api/v2/prospects/79" } } } |
Create Prospect with Assigned Users
POST https://api.outreach.io/api/v2/prospects
Success response code 201
Request payload:
|
{ "data": { "type": "prospect", "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Update Assigned Users for Prospect
Replace All Assigned Users
PATCH https://api.outreach.io/api/v2'/prospects/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "prospect", "id": 79, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Remove All Assigned Users
PATCH https://api.outreach.io/api/v2/prospects/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "prospect", "id": 79, "relationships": { "assignedUsers": { "data": [] } } } } |
Opportunities
Get Opportunity with Assigned Users
Request example:
GET https://api.outreach.io/api/v2/opportunities/{:id}
Success response code 200
Response example:
|
{ "data": { "type": "opportunity", "id": 79, "attributes": { ... }, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 }, { "type": "user", "id": 22 }, { "type": "user", "id": 26 } ], "links": { "related": "https://api.outreach.io/api/v2/users?filter%opportunity%5D%5Bid%5D=79" }, "meta": { "count": 4 } }, "owner": { "data": { "type": "user", "id": 26 } }, ... }, "links": { "self": "https://api.outreach.io/api/v2/opportunities/79" } } } |
Create Opportunity with Assigned Users
POST https://api.outreach.io/api/v2/opportunities
Success response code 201
Request payload:
|
{ "data": { "type": "opportunity", "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Update Assigned Users for Opportunity
Replace All Assigned Users
PATCH https://api.outreach.io/api/v2/opportunities/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "opportunity", "id": 79, "relationships": { "assignedUsers": { "data": [ { "type": "user", "id": 18 }, { "type": "user", "id": 19 } ] } } } } |
Remove Assigned Users
PATCH https://api.outreach.io/api/v2/opportunities/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "opportunity", "id": 79, "relationships": { "assignedUsers": { "data": [] } } } } |
Job Roles
API for working with the type of function a user performs or performed on behalf of a record.
Request example:
GET https://api.outreach.io/api/v2/jobRoles
Success response code 200
Get All Job Roles
Get a list of all job roles.
Request example:
GET https://api.outreach.io/api/v2/jobRoles
Success response code 200
Response example:
|
{ "data": [ { "type": "jobRole", "id": 1, "attributes": { "active": true, "createdAt": "2021-12-08T16:53:52.000Z", "name": "AE", "order": 1, "updatedAt": "2021-12-08T16:53:52.000Z" }, "links": { "self": "https://api.outreach.io/api/v2/jobRoles/1" } }, { "type": "jobRole", "id": 2, "attributes": { "active": true, "createdAt": "2021-12-08T16:53:52.000Z", "name": "BDR", "order": 2, "updatedAt": "2021-12-08T16:53:52.000Z" }, "links": { "self": "https://api.outreach.io/api/v2/jobRoles/2" } }, { "type": "jobRole", "id": 3, "attributes": { "active": true, "createdAt": "2021-12-08T16:53:52.000Z", "name": "CSM", "order": 3, "updatedAt": "2021-12-08T16:53:52.000Z" }, "links": { "self": "https://api.outreach.io/api/v2/jobRoles/3" } }, { "type": "jobRole", "id": 4, "attributes": { "active": true, "createdAt": "2021-12-08T16:53:52.000Z", "name": "SDR", "order": 4, "updatedAt": "2021-12-08T16:53:52.000Z" }, "links": { "self": "https://api.outreach.io/api/v2/jobRoles/4" } } ], "meta": { "count": 4, "count_truncated": false } } |
Get Job Role
Get a single job role by id.
Request example:
GET https://api.outreach.io/api/v2/jobRoles/{:id}
Success response code 200
Response example:
|
{ "data": { "type": "jobRole", "id": 1, "attributes": { "active": true, "createdAt": "2021-12-08T16:53:52.000Z", "name": "AE", "order": 1, "updatedAt": "2021-12-08T16:53:52.000Z" }, "links": { "self": "https://api.outreach.io/api/v2/jobRoles/1" } } }
|
Create Job Role
Create a new job role.
POST https://api.outreach.io/api/v2/jobRoles
Success response code 201
Request payload:
|
{ "data": { "type": "jobRole", "attributes": { "name": "New Role" } } } |
Update Job Role
Update fields of a job role. If the role is not needed, set the active field to false. Note that there isn’t an API to delete a job role.
PATCH https://api.outreach.io/api/v2/jobRoles/{:id}
Success response code 200
Request payload:
|
{ "data": { "type": "jobRole", "id": 5, "attributes": { "name": "New Role Name" } } } |
Add Job Role to User
PATCH https://api.outreach.io/api/v2/users/{:id}
Success response code 200
Request payload:
|
{ "data": { "id":4, "type": "user", "relationships": { "jobRole": { "data": { "type": "jobRole", "id":1 } } } } } |