Skip to content

User API

The User API is used to create, update and delete users on the Relevance platform.

Requirements

  • A feed name and API key (contact your ORTEC service contact to obtain these)
  • The base url of your User API instance
  • A mapping must be defined to transform the incoming user data to the Relevance user profile (this mapping should be discussed with your ORTEC service contact when setting up the feed). This mapping must contain a value that maps to the uid of the user.

Authentication

All calls to the User API must include a feed name and associated API key. These should be included as top-level attributes in any JSON data submitted to the User API.

1
2
3
4
5
  {
    "feed": string,
    "apikey": string,
    [additional fields]
  }

Users

Users are created, updated and deleted by making an HTTP POST to /accounts

  • Content-type should be application/json
  • The post body should contain a JSON object

User data

Each user is submitted as a JSON object, which has the following shape:

1
2
3
4
5
{
  "action": "insert"|"update"|"upsert"|"delete",
  "id": "bsmith@ortec-relevance.com",
  [additional user fields]
}

Unless there are very specific reasons to use the insert and update actions it is simpler to use upsert. In this case a user will be created if she does not exist and will be updated if she does.

Request

Users are placed in an array in the accounts field. Below is an example of a complete request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "feed": API_FEED_NAME,
    "apikey": API_KEY,
    "accounts": [
    {
      "action":"upsert",
      "id": "bsmith@ortec-relevance.com",
      "function": "developer",
      "firstName": "Bob",
      "lastName": "Smith"
    }, 
    {
      "action":"delete",
      "id": "asmith@ortec-relevance.com"
    }
  ]
}

We recommend not sending more than 1000 users in one batch. Sending too many users may result in requests timing out before all the users have been processed.

Response

The user API will return an array of results, with a result for each submitted user:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "results": [
        {
            "status": "ok"
        },
        {
            "error": "current profile not found"
        }
    ]
}