Clients

Client object fields

Example of JSON representation:

{
    "client":
    {
        "name": "MiaRec",
        "client_id": "34cbea90-9201-11e5-a932-e03f497dbdff",
        "tenant_id": "34c7f1f6-9201-11e5-a739-e03f497dbdff",
        "contacts": [{
            "phone_number": "+14085800150",
            "name": "Main number"
        }, {
            "phone_number": "+14085800105",
            "name": "Fax"
        }]
    }
}

Field Type Description
name string Client name.
client_id UUID Unique ID of client assigned by MiaRec when client is created.
tenant_id UUID ID of parent tenant object. This field is available only when multi-tenancy is enabled in MiaRec.
contacts list A of contacts (phone numbers). See object Contact below.

At least one contact is required.

Contact object fields

Field Type Description
phone_number string Phone number associated with contact.

MiaRec application uses phone number to associate call recordings to clients.

Required.

name string Contact name, for example a name of person this phone number belongs to.

Optional.

List and search clients

List all groups:

GET /api/v2/clients.json

Example of response:

{
    "next_url": null,
    "clients": [{
        “client_id”:          “b74e35b0-b6e3-11e8-b938-e03f497dbdff”,
        “tenant_id”:         “156340bf-8b47-21e4-95a4-e03f497dbd44”,
        “name”:              “MiaRec”,
        "contacts": [{
            "phone_number": "+14085800150",
            "name": "Main number"
        }, {
            "phone_number": "+14085800105",
            "name": "Fax"
        }]
    },{
        “client_id”:          “ccb5957a-b6e5-11e8-b66b-e03f497dbdff”,
        “tenant_id”:         “156340bf-8b47-21e4-95a4-e03f497dbd44”,
        “name”:              “Contoso”,
        "contacts": [{
            "phone_number": "1234567890",
            "name": null
        }]
    }]
}

See also Paging through collections

Search groups:

  • Search by client name, contact name, contact phone number and tenant name (in multi-tenant version)

    GET /api/v2/clients.json?search_term=Contoso
    
  • Search by tenant id

    GET /api/v2/clients.json?tenant_id=2bfcefd4-f41d-11e4-983d-e03f497dbdff
    
  • Search by multiple parameters (tenant_id + search_term)

    GET /api/v2/clients.json?tenant_id=2bfcefd4-f41d-11e4-983d-e03f497dbdff&search_term=Contoso
    

View a client

Request to view a client:

GET /api/v2/clients/<client-id>.json

Example of response:

{
    "client": {
        “client_id”:          “b74e35b0-b6e3-11e8-b938-e03f497dbdff”,
        “tenant_id”:         “156340bf-8b47-21e4-95a4-e03f497dbd44”,
        “name”:              “MiaRec”,
        "contacts": [{
            "phone_number": "+14085800150",
            "name": "Main number"
        }, {
            "phone_number": "+14085800105",
            "name": "Fax"
        }]
    }
}

Create a client

Request to create new client:

POST /api/v2/clients.json

HTTP body should contain JSON formatted profile of client to create.

For example:

{
    "client": {
        “tenant_id”:         “156340bf-8b47-21e4-95a4-e03f497dbd44”,
        “name”:              “Contoso”,
        "contacts": [{
            "phone_number": "1234567890",
            "name": null
        }]
    }
}

Response contains HTTP status code as shown in the following table.

Response Description
201 Created Client has been successfully created. HTTP header Location contains URL by which the newly created object should be know.

For example:

HTTP/1.1 201 Created
Location: /api/v2/clients/e011c408-f288-11e4-9b73-e03f497dbdff.json

403 Forbidden The request cannot be completed because API user has no permission to create clients
400 Bad Request The request cannot be completed because supplied JSON object has invalid data.

When response has content type application/json, then it contains more detailed description of error in JSON format like:

{
    "error": "InvalidRecord",
    "description": "Record Validation errors",
    "details": [
        "name": "Client with such name exists already"
   ]
}

Update a client

Request to update existing client:

PUT /api/v2/clients/<client-id>.json

HTTP body should contain JSON formatted profile of client to update.

For example:

{
    "client": {
        "name": "New Client Name"
    }
}

Response contains HTTP status code as shown in the following table.

Response Description
200 OK Client has been successfully updated.

A response contains a JSON formatted client's data after update.

403 Forbidden The request cannot be completed because API user has no permission to edit groups
400 Bad Request The request cannot be completed because supplied JSON object has invalid data.

When response has content type application/json, then it contains more detailed description of error in JSON format like:

{
    "error": "InvalidRecord",
    "description": "Record Validation errors",
    "details": [
        "name": "Client with such name exists already"
   ]
}

Delete a client

Request to delete a particular client:

DELETE /api/v2/clients/<client-id>.json

Response contains HTTP status code as shown in the following table.

Response Description
200 OK Client has been successfully deleted

403 Forbidden The request cannot be completed because API user has no permission to delete clients