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": [] } } } } |
Individual Assignments management API
Individual Assignments in the Outreach data model has management endpoints exposed under the /api/v2/recordActorAssignments area. That allows manipulation with individual assignments separately, not only as a whole set at once.
Individual assignments form a 1:1 link between respective objects (Ex: Accounts and assigned User).
Note: The described recordActorAssignments endpoints are not tied to specific objects like Account, Prospect etc. but operate exclusively using their own IDs. That is because individual Assignments are in fact separate data entities, they aren’t part of the parent record. As a result, they have dedicated IDs, separate management API and variable Record or Actor types that can be used on them.
Supported Record types
|
Account |
|
Prospect |
|
Opportunity |
Supported Actor types
Actor describes the type of entity assigned to the main record. Currently, the only supported kind of the Actor is User but that might extend in the future.
| User |
Record Actor Assignments API Endpoints
Create individual assignment
POST https://api.outreach.io/api/v2/recordActorAssignments
Success response has HTTP Status code 200
Request payload:
|
{ "data": { "type": "recordActorAssignment", "attributes": { "actorType": "User", "actorId": 1, "recordType": "Account", "recordId": 123 } } } |
Query the Assignments
GET https://api.outreach.io/api/v2/recordActorAssignments
- Note that response is paginated (see “links” response node)
- Operating on a FULL set of ALL assignments, hence this list might be huge!
Supported filtering parameters (should be combined to limit the result set):
|
actorId |
ID of the Assigned User |
|
actorType |
Type of the Assigned entity (initially only the User is supported) [User] |
|
recordId |
ID of the Object Assignment is linked to |
|
recordType |
Type of record Assignment is linked to [Account/Prospect/Opportunity/…] |
The resulting response is paginated (see links section for page URLs)
Response example:
|
{ "data": [ { "type": "recordActorAssignment", "id": 12345, "attributes": { "actorId": 12, "actorType": "User", "createdAt": "2021-10-28T00:04:28.000Z", "recordId": 44, "recordType": "Account", "updatedAt": "2021-10-28T00:04:28.000Z" }, "relationships": { "actor": { "data": { "type": "user", "id": 12 } }, "record": { "data": { "type": "account", "id": 44 } } }, "links": { "self": "https://api.outreach-staging.com/api/v2/recordActorAssignments/12345" } }, … ], "meta": { "count": 9095, "count_truncated": false }, "links": { "last": "https://api.outreach-staging.com/api/v2/recordActorAssignments?page%5Boffset%5D=9050", "next": "https://api.outreach-staging.com/api/v2/recordActorAssignments?page%5Boffset%5D=50" } } |
Query an individual Assignment details
Request example:
GET https://api.outreach.io/api/v2/recordActorAssignments/{id}
Response example:
|
{ "type": "recordActorAssignment", "id": 12345, "attributes": { "actorId": 12, "actorType": "User", "createdAt": "2021-10-28T00:04:28.000Z", "recordId": 44, "recordType": "Account", "updatedAt": "2021-10-28T00:04:28.000Z" }, "relationships": { "actor": { "data": { "type": "user", "id": 12 } }, "record": { "data": { "type": "account", "id": 44 } } }, "links": { "self": "https://api.outreach-staging.com/api/v2/recordActorAssignments/12345" } } |
Delete an individual Assignment
Request example:
DELETE https://api.outreach.io/api/v2/recordActorAssignments/{id}
Endpoint usable only by the User with Admin role
Returns HTTP Status 204 (No Content) after successful delete
Update an individual Assignment
PATCH https://api.outreach.io/api/v2/recordActorAssignments/{id}
Endpoint usable only by the User with Admin role
Allows to replace individual Assignee to the different User for example:
Request payload:
|
{ "data": { "type": "recordActorAssignment", "id": 123, "attributes": { "actorType": "User", "actorId": 12345 } } } |
Response example:
|
{ "data": { "type": "recordActorAssignment", "id": 123, "attributes": { "actorId": 12345, "actorType": "User", "createdAt": "2022-04-11T10:59:43.000Z", "recordId": 8, "recordType": "Account", "updatedAt": "2022-04-11T11:03:02.000Z" }, "relationships": { "actor": { "data": { "type": "user", "id": 12345 } }, "record": { "data": { "type": "account", "id": 8 } } }, "links": { "self": "https://api.outreach.io/api/v2'/recordActorAssignments/123" } } } |
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 } } } } } |
© 2023 Outreach.io