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
id 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/{id}   

{
    "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/{id}    

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/{id}    

Deletion is permanent.

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