https://api.movidesk.com/public/v1

People

Note: The password created for this API must contain at least 8 digits.

  URL:    /persons
  Methods: GET / POST / PATCH / DELETE

Layout

person

People » Addresses

person.addresses[n]

People » Contacts

person.contacts[n]

People » Emails

person.emails[n]

People » Organizations

person.relationships[n]

People » Organization » Services

person.relationships[n].services[n]

People » Custom Fields

person.customfieldvalues[n]

People » Custom Fields » Items

person.customfieldvalues.items[n]

People » Assets

person.atAssets[n]

*UTC: Coordinated Universal Time (from English Universal Time Coordinated) is the reference time zone from which all other time zones in the world are calculated. For example: If your time zone is Brasília (UTC-03:00) and the current time is 15:30, the UTC time will be 18:30.

All data flows (Viewing/Inserting/Updating) must be in JSON format as shown in the example below:

{ "id": "1", "codeReferenceAdditional": "33B", "isActive": true, "personType": 1, "profileType": 3, "accessProfile": "Administrators", "businessName": "Movidesk", "corporateName": "Movimentti systems", "cpfCnpj": "012345678900", "userName": "admin", "password": null, "role": null, "bossId": null, "classification": null, "cultureId": "en-US", "timeZoneId": "America/Sao_Paulo", "createdDate": "2014-12-17T18:00:43.3339728", "observations": "Registration done via person API.", "addresses": [ { "addressType": "Commercial", "country": "Brazil", "postalCode": "89035200", "state": "Santa Catarina", "district": "Vila Nova", "street": "Rua Joinville", "number": "209", "complement": "Room 201", "reference": "Next to FURB", "isDefault": true } ], "contacts": [ { "contactType": "Business phone", "contact": "(47) 3035-4150", "isDefault": true }, { "contactType": "Mobile phone", "contact": "(47) 9999-9999", "isDefault": false } ], "emails": [ { "emailType": "Professional", "email": "atendimento@movimentti.movidesk.com", "isDefault": true } ], "teams": [ "Administrators", "Consulting" ], "relationships": [ { "id": "2113", "name": "Movimentti", "slaAgreement": "Standard SLA contract", "forceChildrenToHaveSomeAgreement": false, "allowAllServices": false, "services": [ { "id": 5706, "name": "Support" } ] } ], "customFieldValues": [ { "customFieldId": 3, "customFieldRuleId": 2, "line": 1, "value": null, "items": [ { "personId": null, "clientId": null, "team": null, "customFieldItem": "one" } ] }, { "customFieldId": 1, "customFieldRuleId": 1, "line": 1, "value": "text via API", "items": [] } ] }

Fetching a single person

GET: /persons
 Parameters: id, token

Example:

Fetching the person with id 1

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1

Response:

  {
    "id": "1",
    "codeReferenceAdditional": "33B",
    "isActive": true,
    "personType": 1,
    "profileType": 3,
    "accessProfile": "Administrators",
    "businessName": "Movidesk",
    "corporateName": "Movimentti systems",
    "cpfCnpj": "012345678900",
    "userName": "admin",
    ... Other columns in the format of the above layout
  }

Fetching a list of people

GET: /persons
 Parameters: token

Example:

Fetching a list of people

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176

Response:

  [
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 3,
      "accessProfile": "Administrators",
      "businessName": "Movidesk",
      "corporateName": "Movimentti systems",
      "cpfCnpj": "012345678900",
      "userName": "admin",
      ... Other columns in the format of the above layout
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 1,
      "accessProfile": "Clients",
      "businessName": "Client A",
      "corporateName": "Client A",
      "cpfCnpj": "012345678901",
      "userName": "clientA",
      ... Other columns in the format of the above layout
    }
    ... Other items in the list 
  ]

Fetching people with filters

GET: /persons
Parameters: token

To enable and simplify queries with filters, the API uses the open protocol OData. The possible filters are:
• $filter: the expression specified with this filter is evaluated for each item in the query result, and only the items where the expression result is true will be included in the final result;
• $orderby: allows the items in the query result to be ordered either ascending (asc) or descending (desc). If neither asc nor desc is specified, the default will be asc;
• $top: allows specifying the number of items that should be included in the query result;
• $skip: allows specifying the number of items that should be skipped and not included in the query result;
• $select: allows specifying specific properties of the items that should be filled in the query result;
• $expand: allows expanding the child collections of the queried items.

Note: $select clauses are always ignored when they are inside an $expand. That is, when an $expand exists, the API returns all available parameters in the array, and it is not possible to limit.

Examples:

Fetching a list of people who are of client profile type:

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2

Response:

[
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clients",
      "businessName": "Client A",
      "corporateName": "Client A",
      "cpfCnpj": "012345678900",
      "userName": "clientA",
      ... Other columns in the format of the above layout
    },
    {
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true,
      "personType": 1,
      "profileType": 2,
      "accessProfile": "Clients",
      "businessName": "Client B",
      "corporateName": "Client B",
      "cpfCnpj": "012345678901",
      "userName": "clientB",
      ... Other columns in the format of the above layout
    }
    ... Other items in the list with profileType equal to 2
  ]

Fetching a list of people who are of client type and ordered in descending order by id:

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2&$orderby=id desc

Response:

[
    { 
      "id": "2",
      "codeReferenceAdditional": "34B",
      "isActive": true, "personType": 1,
      "profileType": 2, "accessProfile": "Clients",
      "businessName": "Client B",
      "corporateName": "Client B",
      "cpfCnpj": "012345678901",
      "userName": "clientB",
       ... Other columns in the format of the above layout },    
    {
      "id": "1",
      "codeReferenceAdditional": "33B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clients",
      "businessName": "Client A",
      "corporateName": "Client A",
      "cpfCnpj": "012345678900",
      "userName": "clientA",
      ... Other columns in the format of the above layout
    }    
    ... Other items in the list sorted in descending order by id and with profileType equal to 2
  ]

Fetching a list of people who are of client type, sorted in descending order by id and filtering the result to get only 100 people, while skipping the first 100 (used for pagination of the result, in this case to get the second page):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Response:

[
    { 
      "id": "102",
      "codeReferenceAdditional": "134B",
      "isActive": true, 
      "personType": 1,
      "profileType": 2, 
      "accessProfile": "Clients",
      "businessName": "Client B",
      "corporateName": "Client B",
      "cpfCnpj": "012345678901",
      "userName": "clientB",
       ... Other columns in the format of the above layout },    
    {
      "id": "101",
      "codeReferenceAdditional": "133B",
      "isActive": true,
      "personType": 2,
      "profileType": 2,
      "accessProfile": "Clients",
      "businessName": "Client A",
      "corporateName": "Client A",
      "cpfCnpj": "012345678900",
      "userName": "clientA",
      ... Other columns in the format of the above layout
    }    
    ... Other 98 items in the list sorted in descending order by id and with profileType equal to 2
  ]

Fetching the id and name of people who are of client type, sorted in descending order by id and filtering the result to get only 100 people, while skipping the first 100 (used for pagination of the result, in this case to get the second page):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$select=businessName,id&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Response:

[
    { 
      "id": "102", 
      "businessName": "Client B"
    },    
    {
      "id": "101",     
      "businessName": "Client A"    
    }    
    ... Other 98 items in the list sorted in descending order by id and with profileType equal to 2
  ]

Fetching the id, name, organizations, and allowed services of people who are of client type, sorted in descending order by id and filtering the result to get only 100 people, while skipping the first 100 (used for pagination of the result, in this case to get the second page):

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$select=businessName,id&$expand=relationships($expand=services)&$filter=profileType eq 2&$orderby=id desc&$top=100&$skip=100

Response:

[
    { 
      "id": "102", 
      "businessName": "Client B",  
      "relationships": [
      {
        "id": "2113",
        "name": "Movimentti",
        "slaAgreement": "Standard SLA Agreement",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": false,
        "services": [
         {
           "id": 5706,
           "name": "Support"
         }
       ]
      }
    ]},    
    {
      "id": "101",     
      "businessName": "Client A",  
      "relationships": [
      {     
        "slaAgreement": "Standard SLA Agreement",
        "forceChildrenToHaveSomeAgreement": false,
        "allowAllServices": true,
        "services": []
      }
    ]}
    }    
    ... Other 98 items in the list sorted in descending order by id and with profileType equal to 2
]

Fetching people who have at least one email equal to "email@movidesk.com":

GET: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&$filter=Emails/any(e: e/email eq 'email@movidesk.com')

Response:

[
    { 
      "id": "102", 
      "businessName": "Client B",  
      ... Other properties of the person  
      "emails": [
      {
       "emailType": "Commercial",
       "email": "email@movidesk.com",
       "isDefault": true
      },
      {
       "emailType": "Personal",
       "email": "other.email@movidesk.com",
       "isDefault": false
      }],    
    {
      "id": "101",     
      "businessName": "Client A",
      ... Other properties of the person  
      "emails": [
      {
       "emailType": "Commercial",
       "email": "email@movidesk.com",
       "isDefault": true
      }
    ]}
    }    
    ... Other items in the list that contain at least one email equal to "email@movidesk.com"
]

POST: /persons
 Parameters: token, returnAllProperties (default value is false)
 Headers: Content-Type: application/json
 Request Body: {JSON object}

Example:

POST: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&returnAllProperties=false
Headers: Content-Type: application/json
RequestBody:
{
  "id": "1",
  "codeRefAdditional": "33B",
  "isActive": true,
  "personType": 2,
  "profileType": 3,
  "accessProfile": "Administrators",
  "businessName": "Movidesk",
  "corporateName": "Movimentti sistemas",
  "cpfCnpj": "012345678900",
  "userName": "admin",
  ... Other columns in the format of the layout above
}

Response: Status 200 and in the body the id (reference code) of the inserted person.

POST: /persons/relationships
 Parameters: token, id
 Headers: Content-Type: application/json
 Request Body: {JSON object}

Example:

Including the relationship of person with id 1 with organization of id 123

POST: https://api.movidesk.com/public/v1/persons/relationships?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "relationships": [
        {
             "id": "123",
             "allowAllServices": true
        }
  ]
}

Response: Status 200 

Unlike data insertion (POST), updating is done partially. Thus, it is necessary to send only the data that you want to change to the server.

However, modifying lists (child objects) always overwrites all items in the list.

PATCH: /persons
 Parameters: token, id
 Headers: Content-Type: application/json
 Body: {JSON object}

Examples:

Changing the name of the person with id 1

PATCH: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "businessName": "Movidesk"
}

Response: Status 200

In the example above, only the businessName field is changed; other fields remain unchanged

Removing the emails of the person with id 1

PATCH: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json
RequestBody:
{
  "emails": []
}

Response: Status 200

As emails are in a list, in the example above, all emails are removed. This is because the values provided in the list always overwrite the previously stored values.

DELETE: /persons
Parameters: token, id
Headers: Content-Type: application/json
Request Body: {JSON object}

Examples:

Deleting the person with id 1

DELETE: https://api.movidesk.com/public/v1/persons?token=52ee6ca5-8639-422b-bafe-470013c11176&id=1
Headers: Content-Type: application/json

Response: Status 200

try
{
   var person = new
   {
     isActive = true
   };
   var json = JsonConvert.SerializeObject(person);

   var response = await SendAsync("https://api.movidesk.com/public/v1/persons?token=YOURTOKEN",
   json, "POST", "application/json"); 
}
catch (WebException ex)
{
   var response = new StreamReader(ex.Response.GetResponseStream()).ReadToEnd();
}

public static async Task<string> SendAsync(string uri, string content, string method, string contentType)
{
  var req = WebRequest.Create(uri);
  req.ContentType = contentType;
  req.Method = method;

  using (var stream = await req.GetRequestStreamAsync())
  using (var streamWriter = new StreamWriter(stream))
  {
    await streamWriter.WriteAsync(content);
  }

  var httpResponse = (HttpWebResponse)await req.GetResponseAsync();
  using (var stream = httpResponse.GetResponseStream())
  {
    if (stream == null)
       return null;

    using (var streamReader = new StreamReader(stream))
    { 
       return await streamReader.ReadToEndAsync();
    }
  }
}