Persons API

The Persons API allows you to retrieve, create, update, and delete persons.

Persons are a core resource referenced by other endpoints.

Person object

Field Type Description
personId number Person identifier
firstName string First name
lastName string Last name
userName string User name
information string General information
active boolean Whether the person is active

Get all persons

GET /api/v1/persons    

{
    "data": [
        {
            "personId": 1,
            "firstName": "Eemi",
            "lastName": "Ahola",
            "active": false,
            "userName": "eemi.ahola",
            "information": "additional information..."
        },
        {
            "personId": 100,
            "firstName": "John",
            "lastName": "Doe",
            "active": true,
            "userName": "john.doe@deltabit.com",
            "information": ""
        },
...
}

Get a person by identifier

GET /api/v1/persons/{identifier}   

 Identifier can be personId or userName.

{
    "data": {
        "personId": 1,
        "firstName": "John",
        "lastName": "Doe",
        "active": false,
        "userName": "john.doe",
        "information": "additional information..."
    }
}

Create or update multiple persons

PUT /api/v1/persons    

Only the provided fields are updated. If the person does not exist, a new one is created.

{
    "data": [
        {
            "personId": 1,
            "firstName": "Eemi",
            "lastName": "Ahola",
            "active": false,
            "userName": "eemi.ahola",
            "information": "additional information..."
        },
        {
            "personId": 100,
            "firstName": "John",
            "lastName": "Doe",
            "active": true,
            "userName": "john.doe@deltabit.com",
            "information": ""
        },
...
}

Response

{
    "status": {
        "created": [],
        "updated": [ 1 ],
        "unchanged": [ 100 ]
    },
    "data": [
        { "personId": 1 },
        { "personId": 100 }
    ]
}

Create or update a person

PUT /api/v1/persons/{identifier}    

 Identifier can be personId or userName. 

Possible status values:

  • created     
  • updated     
  • unchanged     
{
    "data": {
        "firstName": "John",
        "lastName": "Doe",
        "active": false,
        "userName": "john.doe",
        "information": "additional information..."
    }
}

Response

{
    "status": "unchanged",
    "data": { "personId": 1 }
}

Delete a person

DELETE /api/v1/persons/{identifier}     

 Identifier can be personId or userName.

Deletion is permanent.

Recommendation: set the person as inactive (active = false ) instead of deleting.