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. In the case of GET requests they are included as query parameters.

  {
    "feed": string,
    "apikey": string,
    [additional fields]
  }

Creating, Updating and Deleting 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:

{
  "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:

{
    "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:

{
    "results": [
        {
            "status": "ok"
        },
        {
            "error": "current profile not found"
        }
    ]
}

Getting a user

You can get a user by uid by making an HTTP GET to /uid/{uid}

Request

Feed and API Key should be provided in the feed and apikey query params.

Response

If the user exists the user's profile will be returned. If the user does not exist HTTP 404 Not Found will be returned.

Searching for users

You can search for users by making an HTTP GET to /profiles.

Request

Feed and API Key should be provided in the feed and apikey query params.

Search terms are provided in the query parameters. The following search terms are supported:

Query Param	Description	Example
q	The search term	Doe
q_f	The external name of the profile field to search. This external name will be mapped to a profile field by the mappings associated with the Feed.	lastName
q_o	Query operator. Depending on the type of the field being searched on this can take multiple values. For a Date, it can be "s" (greater than equal) or "e" (less than or equal), default is within the day of the date specified. For a text field it can be "s" (start with) or "e" (ends with), default contains.	s
offset	Offset in the result set. Defaults to 0.	50
limit	The maximum number of results to return. Defaults to 50.	100
sort	The order in which to sort the results, -1 or 1. Defaults to 1.	-1
anonymous	Whether or not to include anonymous profiles. 0 (not anonymous) or 1 (anonymous)	0

Response

The profiles matching the query are returned, as well as pagination links.

{
  "profiles": [], // Profiles matching the query
  "_links": {
    "self": {
      "href": "/profiles?feed=305-azure-user-sync&apikey=BBC31CD0CE62D93AAE30A15570DA74C5&q=evans&q_f=lastName"
    },
    "first": {
      "href": "/profiles?feed=305-azure-user-sync&apikey=BBC31CD0CE62D93AAE30A15570DA74C5&offset=0&limit=50&q=evans&q_f=lastName"
    },
    "last": {
      "href": "/profiles?feed=305-azure-user-sync&apikey=BBC31CD0CE62D93AAE30A15570DA74C5&offset=0&limit=50&q=evans&q_f=lastName"
    }
  }
}