Accounts

User accounts allow login and interaction with VOCUS apps.

Account Properties

The data model for synchronizing an account.

Field Type Constraints Notes

accountId string 50 Required This is a Mapped ID.

firstName string 50 Required

middleName string 50

lastName string 50

email string 100 Required VOCUS requires every user to have an email address. This value will also be used as the account's login user name.

dateOfBirth date Date of Birth can make certification/currency calculations in FlightRisk more accurate.

designations

array

An array of designation objects that contain a designation string and a boolean active value.

Field	Type	Constraints	Notes
isActive	boolean		Set to true to specify that the designation is currently in use. If `isActive` is omitted, this value defaults to false.
designation	string	Required	Valid values (case-insensitive): `pilot` `flightEngineer` `flightAttendant` `experimentalPilot` `contractPilot` `maintenance` `dispatch`

/Accounts/

HTTP PUT Service Accounts

Creates a user account if it doesn't exist. If the account already exists, it will not be modified, but a mapping for accountId will be added.

Request

See Account Properties.

Example Payload

        {
          "accountId": "callers_ID_12345",
          "firstName": "Jane",
          "middleName": "B",
          "lastName": "Tester",
          "email": "jane@example.org",
          "dateOfBirth": "1980-08-01T00:00Z",
          "designations": [
            {
              "isActive": "true",
              "designation": "pilot"
            },
            {
              "isActive": "true",
              "designation": "flightEngineer"
            }
          ]
        }

Response

See HTTP Response Codes

HTTP Status

Data

201

Field	Type	Detail
accountId	Integer	VOCUS' ID for the account.

200

Field	Type	Detail
accountId	Integer	VOCUS' ID for the account.
newSourceMappingAdded	Boolean	If true, the object was located by a "soft match", not by ID. A mapping was added for the ID provided by the caller.

/Accounts/Deactivate/{id}

HTTP POST Service Accounts

Deactivates an account.

/Accounts/Reactivate/{id}

HTTP POST Service Accounts

Reactivates an account.

/Accounts/Bulk

HTTP PUT Service Accounts

Creates or maps multiple accounts.

Request

Field	Type	Constraints	Detail
accounts	Array	Required	An array of accounts. See Account Properties.

Field

Type

Constraints

Detail

accounts

Array

Required

An array of accounts.

See Account Properties.

Example Payload

        {
          "accounts": [
            {
              "accountId": "callers_ID_12345",
              "firstName": "Jane",
              "middleName": "B",
              "lastName": "Tester",
              "email": "jane@example.org",
              "dateOfBirth": "1980-08-01T00:00Z",
              "designations": [
                {
                  "isActive": "true",
                  "designation": "pilot"
                }
              ]
            },
            {
              "accountId": "callers_ID_67890",
              "firstName": "John",
              "middleName": "P",
              "lastName": "Tester",
              "email": "john@example.org",
              "dateOfBirth": "1985-09-01T00:00Z",
              "designations": [
                {
                  "isActive": "true",
                  "designation": "pilot"
                }
              ]
            }
          ]
        }

Response

See HTTP Response Codes

Because this is a bulk operation, some accounts may be created, others have a new mapping applied, others have no action taken. It is also possible for one or more accounts to have failed validation.

The response code will still be HTTP 200 even when creation occurs, or validation failures occur.

Field Type Detail

operations

Array

An array containing one entry per account submitted.

Field	Type	Detail
operationId	String	This will contain the caller's ID for the account. If the ID was missing (and thus caused a validation failure), this value will be blank.
isValid	Boolean	Indicates whether validation was successful for this account in the batch.
validation	Object	If `isValid` is true, this property will be missing or null. However, if validation failed, this property will contain detail about the failed validation operation.
accountId	Integer	VOCUS' ID for the account. If `isValid` is false, this property will be missing or null.
wasCreated	Boolean	Indicates whether the account was created in VOCUS. If `isValid` is false, this property will be missing or null.
newSourceMappingAdded	Boolean	If true, the object was located by a "soft match", not by ID. A mapping was added for the ID provided by the caller. If `isValid` is false, this property will be missing or null.

Example Bulk Request and Response Payloads

This example shows 2 valid and 2 invalid operations.

Request

        {
          "accounts": [
            {
              "accountId": "callers_ID_12345",
              "firstName": "Jane",
              "middleName": "B",
              "lastName": "Tester",
              "email": "jane@example.org",
              "dateOfBirth": "1980-08-01T00:00Z"
            },
            {
              "accountId": "callers_ID_67890",
              "firstName": "John",
              "middleName": "P",
              "lastName": "Tester",
              // left blank to trigger validation
              "email": "",
              "dateOfBirth": "1985-09-01T00:00Z"
            }
          ]
        }

Response

        {
          "operations": [
            {
              "isValid": true,
              "operationId": "callers_ID_12345",
              "accountId": 112345,
              "wasCreated": false,
              "newSourceMappingAdded": false
            },
            {
              "operationId": "callers_ID_67890",
              "isValid": false,
              "validation": {
                "fieldErrors": {
                  "email": [
                    "Email is required."
                  ]
                },
                "generalErrors": [],
                "isValid": false,
                "title": "Error Validating Input Data",
                "instance": "de8d595d-7a20-4c30-9c33-19ece0d672bb",
                "type": "http://api.polarisaerodev.com/Help/Home/RestConcepts#validation-errors",
                "detail": "Email is required."
              }
            }
          ]
        }

API Version 14.2.9281.28219