forio Toggle navigation

User API

The User API provides create, read, update, and delete (CRUD) capabilities for users of the Epicenter platform.

IMPORTANT: As an Epicenter author, you will probably only ever work directly with end users. If you are a team member, you can use either your user access token or your project access token to make User API requests.

The User API supports the following HTTP methods:

POST: Creating a User

Use the User API POST method to create a new user.

Creating a Single End User

Method: POST

URI: /v2/user

Headers:

  • Content-Type: application/json
  • Authorization: Bearer{access token}

Body: JSON object with the userName, password, account, and at least one of firstName, lastName.

Return Status:

  • 201: User successfully added
  • 409: Conflict, for example, an existing user with the same userName in this team.

Return Body: The user record (JSON object).

Example:

curl -X POST 'https://api.forio.com/v2/user' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
        --data '{"userName": "testUser", "account": "acme", "password": "passw0rd", "firstName": "test", "lastName": "User"}'

Example Resonse:

{
  "created": "2017-01-09T17:13:54.075Z",
  "lastModified": "2017-01-09T17:13:54.075Z",
  "id": "000001597c7d2b1b1bb751499375050d90f9",
  "account": "acme",
  "userName": "testUser",
  "firstName": "test",
  "lastName": "User",
  "verified": false,
  "active": true
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • In the request body, the following fields are required:
    • account: The Team ID.
    • userName: The username for this user. For creating end users, the userName is not required to be an email and only needs to be unique within the team.
    • password: The password for this user. Must contain at least: one letter, one number, and between 8 and 255 characters.
    • At least one of firstName and lastName: The full name of the user.
  • In the request body, the following fields are optional:
    • bio: A text description about the user.
    • homePage: A URL associated with the user, for example a personal blog, Twitter account, or GitHub page.
    • externalSource: A string identifying the third party system of record for this user. When externalSource is present, the combination of userName, account, and externalSource must be unique. That is, you can have multiple end users in an account with the same userName if they have different externalSource fields.
      • Currently externalSource is only used with one Forio customer; please contact us if you are interested in pursuing this option.
  • Epicenter administrators can also create users that are Epicenter authors (not end users). In this case, account is not required in the request body, and userName is required to be an email address.

Creating Multiple End Users at Once

Method: POST

URI: /v2/user

Headers:

  • Content-Type: application/json
  • Authorization: Bearer{access token}
  • X-Force-Action: true (optional)

Body: Array of JSON objects with the userName, password, account, and at least one of firstName, lastName.

Return Status:

  • 201: User successfully added
  • 400: If there are duplicates or if there are rows with invalid fields. Users are created for all valid non-duplicate records.

Return Body:

  • An array of user records that are saved (created);
  • An array of user records that are duplicates;
  • An array of user records that are updated (only contains elements if you are using the X-Force-Action: true header);
  • An array of user records with errors.

Example:

curl -X POST 'https://api.forio.com/v2/user' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
        --data '[{"userName": "user1", "account": "acme-simulations", "password": "passw0rd", "firstName": "user1"}, {"userName": "user2", "account": "acme-simulations", "password": "passw0rd", "firstName": "user2"}, {"userName": "user3", "account": "acme-simulations", "password": "passw0rd"}]'

Example Response:

{
  "saved": [
    {
      "created": "2017-01-09T21:22:11.999Z",
      "lastModified": "2017-01-09T21:22:11.999Z",
      "id": "0000015984e07e3c637540c3aaf060e380e4",
      "account": "acme",
      "userName": "user1",
      "firstName": "user1",
      "verified": false,
      "active": true
    },
    {
      "created": "2017-01-09T21:22:12.235Z",
      "lastModified": "2017-01-09T21:22:12.235Z",
      "id": "0000015984e07e3c637540c3aaf060e380e5",
      "account": "acme",
      "userName": "user2",
      "firstName": "user2",
      "verified": false,
      "active": true
    }
  ],
  "updated": [],
  "duplicate": [],
  "errors": [
    {
      "account": "acme",
      "userName": "user3",
      "verified": false,
      "active": false
    }
  ]
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • To force a duplicate record to be saved (and so overwrite any existing data), add the header X-Force-Action: true to your request.
  • In the request body, the following fields are required:
    • account: The Team ID.
    • userName: The username for this user. For creating end users, the userName is not required to be an email and only needs to be unique within the team.
    • password: The password for this user. Must contain at least: one letter, one number, and between 8 and 255 characters.
    • At least one of firstName and lastName: The full name of the user.
  • In the request body, the following fields are optional:
    • bio: A text description about the user.
    • homePage: A URL associated with the user, for example a personal blog, Twitter account, or GitHub page.
    • externalSource: A string identifying the third party system of record for this user. When externalSource is present, the combination of userName, account, and externalSource must be unique. That is, you can have multiple end users in an account with the same userName if they have different externalSource fields.
      • Currently externalSource is only used with one Forio customer; please contact us if you are interested in pursuing this option.
  • Epicenter administrators can also create users that Epicenter authors (not end users). In this case, account is not required in the request body, and userName is required to be an email address.

GET: Viewing Details about End Users in your Team

You can retrieve details about end users of a specific project in your team with the User API GET method.

Retrieving Details about All End Users in your Team

Method: GET

URI: /v2/user/

Headers:

  • Authorization: Bearer{project access token}

Return Status: 200 (successful response)

Return Body: Any array of records (JSON object) for the user.

Example:

curl -G \
    'https://api.forio.com/v2/user/' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
  {
    "created": "2017-01-09T21:21:51.000Z",
    "lastModified": "2017-01-09T21:21:51.000Z",
    "id": "0000015984e07e3c637540c3aaf060e380e3",
    "account": "acme",
    "userName": "testUser",
    "firstName": "test",
    "lastName": "User",
    "verified": false,
    "active": true
  },
  {
    "created": "2017-01-09T21:22:11.000Z",
    "lastModified": "2017-01-09T22:35:47.000Z",
    "lastLoggedIn": "2017-01-09T23:35:47.000Z"
    "id": "0000015984e07e3c637540c3aaf060e380e4",
    "account": "acme",
    "userName": "user1",
    "firstName": "user1",
    "verified": false,
    "active": true
  },
  {
    "created": "2017-01-09T21:22:12.000Z",
    "lastModified": "2017-01-09T21:22:12.000Z",
    "id": "0000015984e07e3c637540c3aaf060e380e5",
    "account": "acme",
    "userName": "user2",
    "firstName": "user2",
    "verified": false,
    "active": true
  }
]

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project. The project access token for any of your team's projects provides access to all end users for your team.
  • In the response body, the lastLoggedIn field is present only if the user has logged in.
  • In the response body, the created field may flucuate briefly immediately after the record is created, due to an implementation detail occuring between the Epicenter backend database and its cache.
  • In the response body, the lastModified field may incorrectly reflect the created field. This is a known issue.

Retrieving Details about a Particular End User in your Team

Method: GET

URI: /v2/user/{user id}

Headers:

  • Authorization: Bearer{project access token}

Return Status: 200 (successful response)

Return Body: The record (JSON object) for the user.

Example:

curl -G \
    'https://api.forio.com/v2/user/0000015984e07e3c637540c3aaf060e380e4' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

{
  "created": "2017-01-09T21:42:04.637Z",
  "lastModified": "2017-01-09T21:42:04.637Z",
  "id": "0000015984e07e3c637540c3aaf060e380e4",
  "account": "acme",
  "userName": "user1",
  "firstName": "user1",
  "verified": false,
  "active": true
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project. The project access token for any of your team's projects provides access to all end users for your team.
  • The user id is the internal unique identifier for this user. (It is not the userName.)
  • In the response body, the lastLoggedIn field is present only if the user has logged in.
  • In the response body, the created field may flucuate briefly immediately after the record is created, due to an implementation detail occuring between the Epicenter backend database and its cache.
  • In the response body, the lastModified field may incorrectly reflect the created field. This is a known issue.

Searching for End Users of your Team

Method: GET

URI:

  • Search by exact match for one end user: /v2/user?account={team id}&userName={userName}
  • Search by exact match for multiple end users, if user ids are known: /v2/user?id={user id}&id={another user id}
  • Search by exact match for one end user associated with third party systems: /v2/user?account={team id}&externalSource={external source name}&userName={userName}
  • Search by partial match for multiple end users: /v2/user?account={team id}&q={substring}

Headers:

  • Authorization: Bearer{project access token}

Return Status:

  • 200: successful response
  • 400: invalid request

Return Body: An array of records (JSON objects) with matching users.

Example:

curl -G \
    'https://api.forio.com/v2/user?account=acme-simulations&userName=user1' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9'

Example Response:

[
    {
        "active": true,
        "account": "acme-simulations",
        "id": "b6b313a3-ab84-479c-baea-206f6bff337f",
        "lastName": "user1",
        "created": "2014-10-16T17:30:42.000Z",
        "lastModified": "2014-10-16T17:30:42.000Z",
        "lastLoggedIn": "2015-01-02T00:00:00.000Z",
        "userName": "user1"
    }
]

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project. The project access token for any of your team's projects provides access to all end users for your team.
  • The account is the Team ID.
  • The externalSource indicates that the end user was created by a third party system. (Note that end users may have the same account and userName if they have different externalSource values.)
  • The substring for the q query parameter is a full or partial match to the userName field.
  • The id query parameter can be repeated to return many users at once. (This query is a logical OR: id=b347f&id=a243c returns users whose id matches either query.)

  • You can sort the returned records using the following optional parameters:

    • sort: The field by which to sort. Defaults to lastModified.

    • direction: Whether to order the results ascending (ASC) or descending (DESC). Defaults to ASC.

      For example: curl -G 'https://api.forio.com/v2/user?account=acme-simulations&sort=userName&direction=DESC'.

  • If the search returns no results, an empty JSON object is returned ({ }), but the status code is still 200.
  • In the response body, the created field may flucuate briefly immediately after the record is created, due to an implementation detail occuring between the Epicenter backend database and its cache.
  • In the response body, the lastModified field may incorrectly reflect the created field. This is a known issue.

Paging: Retrieving Many Records at Once

When you use the GET method for an API, your request may return many records at once.

The default page size is 100 (for most APIs) or 1000 (for the Data API). You can limit the number of records returned by adding the Range header.

Method: GET

URI: Any Epicenter API call

Headers: Range: records {i}-{j}

Return Status:

  • 200: Successfully retrieved all records
  • 206: Successfully retrieved the partially complete response, for example if you request records 0-20 and there are 35 records
  • 416: No records are found in a given search range (e.g. Range: records 10-15 when there are only 8 records)

Response Headers:

Whether or not you add the Range header to your request, the response header contains:

Content-Range: records i-j/k

where

  • i is the index of the first record returned
  • j is the index of the last record returned
  • k is the total number of records in the result set, or * if that number is computationally infeasible (for example, because you are querying across multiple projects)

For example, Content-Range: records 0-9/57 or Content-Range: records 20-29/*.

Response Body: An array of records. The array includes only those records indicated in the Content-Range header.

Example:

curl -G \
    'https://api.forio.com/v2/EpicenterAPI' \
    --header 'Range: records i-j'

Notes:

  • If no records are returned, the response body is empty.

  • If you leave off the start index, this is considered an implied start index of 0 rather than an invalid range. The response header includes status code of 200 or 206 depending on the ending index.

  • This use of the Range header is part of the RFC 2616 (see details in Section 14.16 and 14.35).

Using POST to Retrieve Many Records at Once

Sometimes when you would like to use the GET method for an API, your request may require a very long URI, for example: https://api.forio.com/v2/user?id=0b31ee58-6cef-488c-9825-19469376b70c&id=0f97e39b-4d45-475e-b710-8a6459db24cf&id=....

For these situations, Epicenter APIs support the option of using a POST method with additional parameters in place of the GET method.

Method: POST

URI:

  • Any Epicenter API call that supports GET with query parameters
  • Followed by ?_method=GET

Headers:

  • Authorization header as required by the Epicenter API in question (e.g. Authorization: Bearer{project access token})
  • Content-Type: application/json

Body: JSON object describing the query. For example:

  • {"id": ["0b31ee58-6cef-488c-9825-19469376b70c", "0f97e39b-4d45-475e-b710-8a6459db24cf"]}

Return Status:

  • 200: Successfully retrieved records

Return Body: Array of records (JSON objects) returned by the query.

Example:

curl -X POST 'https://api.forio.com/v2/user?_method=GET' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
        --data '{"id": ["0b31ee58-6cef-488c-9825-19469376b70c", "0f97e39b-4d45-475e-b710-8a6459db24cf"]}'

Notes:

  • While using POST and query parameter ?_method=GET to retrieve many records at once is available in all Epicenter APIs, it is generally most useful in the User, Member, and Model Run APIs because of the frequency of doing longer queries with those APIs.

PUT: Replacing a User Record

You can replace an end user record using the User API PUT method.

Method: PUT

URI: /v2/user/{user id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer{access token}

Body: JSON object with the userName, account, and at least one of firstName, lastName. The userName must be identical as in the record you are replacing.

Return Status:

  • 200: Successfully updated user

Return Body: A JSON object with the user record just updated.

Example:

curl -X PUT 'https://api.forio.com/v2/user/b6b313a3-ab84-479c-baea-206f6bff337f' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"userName": "testUser", "account": "acme-simulations", "firstName": "another test", "lastName": "User"}'

Example Response:

{
  "created": "2017-01-09T22:06:13.735Z",
  "lastModified": "2017-01-09T22:16:10.000Z",
  "id": "0000015984e07e3c637540c3aaf060e38158",
  "account": "acme",
  "userName": "user3",
  "firstName": "Updated",
  "lastName": "User",
  "verified": false,
  "active": true
}

Notes:

  • In the header, the access token can be the user access token of a team member or the project access token for this project.
  • The userName can NOT be updated using the PUT request; it can never be changed. However, it must be included in the request body.

PATCH: Partially Updating a User Record

Sometimes you only want to change one field of an end user's record, rather than replace the entire record.

You can partially update an existing user record (that is, replace one or more fields) using the Users API PATCH method.

Method: PATCH

URI: /v2/user/{user id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer{access token}

Body: JSON object with the account and the fields to update.

Return Status:

  • 200: Successfully updated user

Return Body: A JSON object with the user record just updated.

Example:

curl -X PATCH 'https://api.forio.com/v2/user/b6b313a3-ab84-479c-baea-206f6bff337f' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \
    --data '{"firstName": "updated first name", "account": "acme-simulations"}'

Example Response:

    {
        "active": true,
        "account": "acme-simulations",
        "id": "b6b313a3-ab84-479c-baea-206f6bff337f",
        "firstName": "updated first name",
        "lastName": "user1",
        "created": "2014-10-16T17:30:42.000Z",
        "lastModified": "2015-02-06T12:35:53.000Z",
        "userName": "user1"
    }

Notes:

  • The userName attribute can NOT be updated using the PATCH request; it can never be changed.
  • In the header, the access token can be the user access token of a team member or the project access token for this project.

DELETE: Removing a User

You can remove a user using the User API DELETE method.

Removing an End User

Method: DELETE

URI: /v2/user/{user id}

Headers:

  • Authorization: Bearer{access token}

Body: none

Return Status:

  • 200: User successfully deleted

Return Body: The user record (JSON object) just deleted.

Example:

curl -X DELETE 'https://api.forio.com/v2/user/2c572d9a-99df-47ac-938c-5cc50a255b5a' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiJ9' \

Example Response:

{
    "active": true,
    "account": "acme-simulations",
    "id": "2c572d9a-99df-47ac-938c-5cc50a255b5a",
    "firstName": "user1",
    "created": "2015-02-10T21:08:52.000Z",
    "lastModified": "2015-02-10T21:08:52.000Z",
    "userName": "user1"
}

Notes: