✓ SCIM User Management via API

The System for Cross-domain Identity Management (SCIM) specification simplifies managing user identities in cloud-based applications. SCIM aims to reduce the cost and complexity of user management by providing a common user schema and standard protocols for exchanging this information.

Enterprise clients who maintain their own Single Sign-On to manage (register, activate, deactivate, change email address) users within their domain on Upwork platform can use SCIM to automate user management.

Access credentials

URL: https://www.upwork.com/api/v3/scim/v2/{tenantId}/
Tenant ID is provided by Upwork (scim-tenant-id is used for examples below)
Bearer access token is provided by Upwork (scim-access-token is used for examples below)

User attributes

{ 
"schemas": [
  "urn:ietf:params:scim:schemas:core:2.0:User", 
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" 
], 
"userName": "johnsmith", 
"externalId": "3ad36cf6-04c1-4eed-9440-0a86cb612ffd", 
"active": true, 
"emails": [{"type": "work", "value": "johnsmith@domain.com"}], 
"name": {"givenName": "John", "familyName": "Smith"}, 
"addresses": [{"type": "work", "country": "US"}], 
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { 
  "department": "IT" 
  } 
}

Mandatory attributes

Email address: At least one work email address must be specified. In the case of multiple addresses, the primary attribute must be set to true for the primary email address.
Given (first) name
Family (last) name
Country code: There must be at least one work address defined with ISO-3166 Alpha-2 country code.

Important to know

We do not recommend storing optional user data unless necessary. We support a limited number of SCIM attributes; all unsupported attributes are ignored
Updates are only supported for activation, deactivation and email change. Any other attribute updates will not affect the user profiles

Request examples

Create user

Request

Javascript

POST https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users 
Authorization: Bearer {scim-access-token} 
Content-Type: application/scim+json 
Accept: application/scim+json 
{ 
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 
  "userName": "johnsmith", 
  "emails": [{"type": "work", "value": "johnsmith@domain.com"}], 
  "name": {"givenName": "John", "familyName": "Smith"}, 
  "addresses": [{"type": "work", "country": "US"}], 
  "active": true 
}

Response

Javascript

201 Created

Content-Type: application/scim+json
ETag: W/"96b065a4"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
  "userName": "johnsmith",
  "meta": {
    "resourceType": "User",
    "created": "2020-09-23T21:18:11.463Z",
    "lastModified": "2020-09-23T21:18:11.463Z"
    },
  "active": true,
  "addresses": [{"type": "work", "country": "US"}],
  "emails": [{"type": "work", "value": "johnsmith@domain.com"}],
  "name": {"givenName": "John", "familyName": "Smith"}
}

Get user

Request

Javascript

GET https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1

Authorization: Bearer {scim-access-token} 
Accept: application/scim+json

Response

Javascript

200 OK

Content-Type: application/scim+json
ETag: W/"96b065a4"
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
  "userName": "johnsmith",
  "meta": {
    "resourceType": "User",
    "created": "2020-09-23T21:18:11.463Z",
    "lastModified": "2020-09-23T21:18:11.463Z"
  },
  "active": true,
  "addresses": [{"type": "work", "country": "US"}],
  "emails": [{"type": "work", "value": "johnsmith@domain.com"}],
  "name": {"givenName": "John", "familyName": "Smith"}
}

Query users

Request

Javascript

GET https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users?filter=id%20eq%20%224ee540f5-1f69-4e3d-86fb-b32ae79316f1%22&startIndex=1&count=10

Authorization: Bearer {scim-access-token}
Accept: application/scim+json

Response

Javascript

200 OK

Content-Type: application/scim+json 

{ 
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 10,
  "Resources": [
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
    "userName": "johnsmith",
    "meta": {
      "resourceType": "User",
      "created": "2020-09-23T21:18:11.463Z",
      "lastModified": "2020-09-23T21:18:11.463Z",
      "location": "https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1",
      "version": "W/\"96b065a4\""
    }, 
    "active": true,
    "addresses": [{"type": "work", "country": "US"}],
    "emails": [{"type": "work", "value": "johnsmith@domain.com"}],
    "name": {"givenName": "John", "familyName": "Smith"}
    }
  ]
}

Note:

User querying is only supported for a limited number of attributes (id, username, externalId) and conditions (eq, and). Order is not supported.

Patch user (deactivation example)

Request

Javascript

PATCH https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1 

Authorization: Bearer {scim-access-token} 
Content-Type: application/scim+json 
Accept: application/scim+json 
If-Match: W/"96b065a4" 

{ 
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], 
  "operations": [{"op": "replace", "path": "active", "value": false}] 
}

Response

Javascript

200 OK 

Content-Type: application/scim+json 
ETag: W/"66ff0656" 
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1 

{ 
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 
  "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1", 
  "userName": "johnsmith", 
  "meta": { 
    "resourceType": "User", 
    "created": "2020-09-23T21:18:11.463Z", 
    "lastModified": "2020-09-23T22:08:45.559Z" 
  }, 
  "active": false, 
  "addresses": [{"type": "work", "country": "US"}], 
  "emails": [{"type": "work", "value": "johnsmith@domain.com"}], 
  "name": {"givenName": "John", "familyName": "Smith"} 
}

Note:

Filters are not supported for add operation in PATCH requests.

This will not work:

{ 
  "op": "add", 
  "path": "addresses[type eq \"other\"].streetAddress", 
  "value": "221B Baker St." 
}

Composite objects should be added like this:

{ 
  "op": "add", 
  "path": "addresses", 
  "value": [{"type": "other", "streetAddress": "221B Baker St."}] 
}

Replace user (email address change example)

Request

Javascript

PUT https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1 

Authorization: Bearer {scim-access-token} 
Content-Type: application/scim+json 
Accept: application/scim+json 
If-Match: W/"66ff0656" 

{ 
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 
  "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1", 
  "userName": "johnsmith", 
  "active": false, 
  "addresses": [{"type": "work", "country": "US"}], 
  "emails": [{"type": "work", "value": "johnsmith-updated@domain.com"}], 
  "name": {"givenName": "John", "familyName": "Smith"} 
}

Response

Javascript

200 OK

Content-Type: application/scim+json 
ETag: W/"a7b462b8" 
Location: https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1 

{ 
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], 
  "id": "4ee540f5-1f69-4e3d-86fb-b32ae79316f1", 
  "userName": "johnsmith", 
  "meta": { 
    "resourceType": "User", 
    "created": "2020-09-23T21:18:11.463Z", 
    "lastModified": "2020-09-23T22:27:18.114Z" 
  }, 
  "active": false, 
  "addresses": [{"type": "work", "country": "US"}], 
  "emails": [{"type": "work", "value": "johnsmith-updated@domain.com"}], 
  "name": {"givenName": "John", "familyName": "Smith"} 
}

Delete user

Request

Javascript

DELETE https://www.upwork.com/api/v3/scim/v2/{scim-tenant-id}/Users/4ee540f5-1f69-4e3d-86fb-b32ae79316f1 
Authorization: Bearer {scim-access-token}

Response

Javascript

204 No content

Note:

This request deactivates the user account, but does not remove the user from the Upwork platform.

Known limitations

Groups are not supported
Bulk updates are not supported
Discovery endpoints are not supported

Articles in this section

Was this article helpful?

Upwork uses third-party cookies for personalized content, analytics, and advertising. Please enable cookies so you can access all areas of Upwork. Learn more here.

✓ SCIM User Management via API

Access credentials

User attributes

Mandatory attributes

Important to know

Request examples

Create user

Get user

Query users

Note:

Patch user (deactivation example)

Note:

Replace user (email address change example)

Delete user

Note:

Known limitations

Was this article helpful?

Do you need additional help?

Log in for personalized service and assistance.

Expand your Upwork knowledge.