Developer Center

Clients API

Last Updated: Mar 03, 2017 03:21PM CET

URL

/api/clients/{ID} 
/api/clients/{ID}/custominformation/{customFieldId} 
/api/clients/search 
/api/clients/{ID}/documents 
/api/clients/{ID}/documents/PROFILE_PICTURE 
/api/clients/{ID}/documents/SIGNATURE 

Description

Allows you to retrieve, view, store, create and update clients. Clients may have associated information such as their address, custom fields or identification documents. It's also possible to search for clients using information such as as this names or identification document.

Methods

GET Client

Allows retrieving clients either directly by a client ID/key or by looking up a client. When retrieving a client, all his associated information such as his custom fields, addresses and identification documents may also be returned if requested. An empty list is returned if no clients are found.
Any combinations can be used. Note that the lookups by names are case sensitive. If an insensitive lookup is required please use Objects Search API.
Example of possible combinations for lookup a client using search are:
  • first
  • last names
  • birth date
  • id document number
  • branch ID

Parameters

fullDetails Whether to load all the nested fields for the clients as well (true or false). This option is available only when retrieving a specific client.
firstName Used for looking up a client by their first name
lastName Used for looking up a client by their last name
idDocument Looking up a client by their id document number
birthDate Looking up a client by their birthdate
branchId Looking up a client assigned to a branch using branch id/key
centreId Looking up a client assigned to a centre using centre id/key
creditOfficerUsername Looking up a client by the assigned credit officer username *
state Looking up a client by their current state

* creditOfficerUsername is required if the user making the call has the "Credit Officer" role and the option "Can access other credit officers clients" is not activated.



Usage examples
//get the basic clients details using client id
GET /api/clients/8

//get the basic clients details using client encoded key
GET /api/clients/8a27a878491d417601491d48203100d9

//get all clients assigned to the branch with id DB
GET /api/clients?branchId=DB

//get all clients assigned to the branch with encoded key 8a2bbaab4700677d0147008dd39b00ea
GET /api/clients?branchId=8a2bbaab4700677d0147008dd39b00ea

//get all clients assigned to the centre with id DC
GET /api/clients?centreId=DC

//get all clients assigned to the centre with encoded key 8a2bbaab4700677d0147008dd66200fe 
GET /api/clients?centreId=8a2bbaab4700677d0147008dd66200fe

//find a client with last names Jones and id document number 131241
GET /api/clients?lastName=Jones&idDocument=131241

//get the profile picture of the client 131241 
GET /api/clients/131241/documents/PROFILE_PICTURE

//get the signature of the client 131241 
GET /api/clients/131241/documents/SIGNATURE

Samples responses:

//short response without the full details
{
   "encodedKey":"402832b43809601c013809639d6400e5",
   "state":"ACTIVE",
   "id":"8",
   "creationDate":"2012-06-20T12:15:18+0200",
   "lastModifiedDate":"2012-06-28T11:52:33+0200",
   "activationDate":"2012-06-28T11:03:32+0200",
   "firstName":"Vijolica",
   "lastName":"Baba",
   "middleName":"Jay",
   "homePhone":"(77) 159-443",
   "mobilePhone1":"604-271-7041",
   "birthDate":"1987-07-08T00:00:00+0200",
   "gender":"MALE",
   "assignedBranchKey":"402832b43809601c01380963908b0009",
   "loanCycle":0,
   "groupLoanCycle":0,
   "clientLinesOfCredit":[]
}

//full response with all nested objects also returned in the same response
{
"client":{
      "encodedKey":"402832b43809601c013809639d6400e5",
      "state":"ACTIVE",
      "id":"8",
      "creationDate":"2012-06-20T12:15:18+0200",
      "lastModifiedDate":"2012-06-28T11:52:33+0200",
      "activationDate":"2012-06-28T11:03:32+0200",
      "firstName":"Vijolica",
      "lastName":"Baba",
      "middleName":"Jay",
      "homePhone":"(77) 159-443",
      "mobilePhone1":"604-271-7041",
      "birthDate":"1987-07-08T00:00:00+0200",
      "gender":"MALE",
      "notes":"Lives with three daughters and old father. The daughters are learning how to paint so that they can sell the paintings and start helping their mother repaying the loan. ",
      "assignedBranchKey":"402832b43809601c01380963908b0009",
      "loanCycle":0,
      "groupLoanCycle":0,
      "clientLinesOfCredit":[

      ]
   },
   "addresses":[
      {
         "encodedKey":"402832b43809601c013809639f400149",
         "parentKey":"402832b43809601c013809639d6400e5",
         "line1":"Dayka G?bor u. 39.",
         "line2":"",
         "city":"Kiskunmajsa",
         "region":"",
         "postcode":"6137",
         "country":"Canada",
         "indexInList":0
      }
   ],
   "customInformation":[
      {
         "encodedKey":"402832b43809601c01380963a0bf01ad",
         "parentKey":"402832b43809601c013809639d6400e5",
         "customFieldKey":"402832b43809601c013809639beb00dc",
         "customField":{
            "encodedKey":"402832b43809601c013809639beb00dc",
            "name":"Position",
            "type":"CLIENT_INFO",
            "dataType":"STRING",
            "isDefault":false,
            "isRequired":false,
            "indexInList":-1
         },
         "value":"Costume designer",
         "indexInList":0
      },
      {
          "encodedKey": "8a8601b44919805d01491dc1e55c1173",
          "parentKey": "8a08971a4481253301448d41706a101713",
          "customFieldKey": "8a61878248a31c3e0141b28a8b790147",
          "customField": {
              "encodedKey": "8a61870248a41c3e1148b18a8b710147",
              "id": "idvalidated",
              "name": "ID Validated",
              "type": "CLIENT_INFO",
              "dataType": "CHECKBOX",
              "valueLength": "SHORT",
              "isDefault": true,
              "isRequired": false,
              "description": "",
              "customFieldSet": {
                  "encodedKey": "8a61878348B31c8e0149a72995af0067",
                  "name": "Workflow",
                  "notes": "Current state of the process",
                  "createdDate": "2015-01-01T11:38:00+0000",
                  "indexInList": 0,
                  "type": "CLIENT_INFO"
              },
              "indexInList": 0,
              "state": "NORMAL",
              "editableByAllUsers": true
          },
          "value": "TRUE",
          "indexInList": 2,
          "customFieldID": "idvalidated"
      }
   ],
   "idDocuments":[
      {
         "encodedKey":"402832b43832534901383281a46d0008",
         "clientKey":"402832b43809601c013809639d6400e5",
         "documentType":"Passport",
         "documentId":"ABC123",
         "issuingAuthority":"Government",
         "validUntil":"2013-06-01T00:00:00+0200",
         "indexInList":0
      }
   ],
   "groupKeys":[ ]
}

//profile picture base64 encoded 
"data:image/jpg;base64,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"​

* Note 1: Custom fields using a boolean value (such as textboxes) return an uppercase string (TRUE, FALSE)
* Note 2: Images for the profile picture and signature are encoded in base 64. This should be read de decoded in order to generate a binary file representing the image. The format of the image is specified at the beginning of the response.

POST Clients

Mambu allows for the creation and the update of client information. This includes the client information, custom fields, identification documents and the address. The client is returned as a response.
  • if none of the "idDocuments":[],"addresses":[],"customInformation":[] will be provided, only the client information will be updated/stored
  • for JSON update, the developer must specify the identifier({/api/clients/{id}} and provide the encodedKey in JSON ({client: {encodedKey:"someKey"}})
  • if the encoded key/identifier is invalid, an exception code will be returned
  • in order to remove all custom fields, identification documents or addresses, an empty array for them must be provided (example: {client: {encodedKey:"abc", //other client information}, "idDocuments":[],"addresses":[],"customInformation":[]}
  • in order to remove some addresses, identification documents, customInformation from database, the information that will not be provided in the arrays
    • example: for custom fields: 3 custom fields in database, only one provided in the "customInformation" array for update, the other 2 from the database will get deleted and the one from the array will get stored/updated
    • for custom fields the matching to determine the difference between an updated and a new field is done using customFieldID
    • for custom fields - if the custom field ID is invalid or the value is invalid an exception code will be returned
    • for identification documents and addresses the encoded key is used for matching
  • only one address can be stored/updated in database, if the addresses array contains more than one address, only the first address will get stored/updated
  • see Custom Fields API for more information about custom fields and custom fields sets
  • notifications should be sent when a client is created via APIs (If there are templates added for client creation and the client has email address / mobile phone number;

Parameters for Client

firstName Client's first name. Required. *
lastName Client's last name. Required. *
encodedKey Client's encodedKey. Required. **
middleName Client's middle name. *
homephone Client's home phone number *
mobilephone1 Client's mobile phone number *
mobilephone2 Client's mobile phone number *
gender Client's gender (one of MALE or FEMALE) *
email Client's email address - the address format is validated *
birthDate Client's birthdate as ISO standard date *
notes Any additional rich text html notes about the clients *
assignedUserKey Encoded key of the credit officer assigned to the user. Required if the organisations settings are set accordingly.
assignedBranchKey Encoded key of the assigned branch.
assignedCentreKey Encoded key of the assigned centre.
clientRole Contains the field:
"encodedKey". Encoded key of the client role needed, in a JSON object. *
preferredLanguage The preferred language of the user. One from ENGLISH, SPANISH, PORTUGUESE, RUSSIAN, GEORGIAN.

* These fields are editable
**For JSON update purpose only

Parameters for Custom Fields

customFieldID The custom field Id. Required.
value The custom field Value. Required.
customFieldSetGroupIndex The index of the grouped fields in the custom group section. Required.*
  • all used custom fields must be previously created in order to be used (for 'Field Type': 'Clients' in Administration), otherwise an exception code will be returned
*For grouped custom fields only

Parameters for Addresses

line1 Client Street Address - Line 1
line2 Client Street Address - Line 2
city Client Residence City
region Client State/Province/Region
postcode Client Address Zip Postal Code
country Client Residence Country
  • the call will add/update only the first the address from the list, all other addresses will be ignored

Parameters for Identification Documents

documentType The Document Type (example: Passport). Required
documentId The document Id. Required
issuingAuthority The Issuing Authority
validUntil Identification Document expiration date
identificationDocumentTemplateKey The identification of the template used for the document ID. Required if a template exists.
  • all the required identification documents must be provided, otherwise an exception code will be returned

Usage Example

//POST a basic url-encoded client named Trevor Linden
POST "firstName=Trevor&lastName=Linden" /api/clients/
//POST create a simple client using JSON
{
   "client":{
      "firstName":"Trevor",
      "lastName":"Linden",
      "middleName":"Good",
      "homePhone":"7899221665",
      "emailAddress":"trevor.linden@mambu.com",
      "mobilePhone1":"211111111",
      "mobilePhone2":"122222222",
      "gender":"MALE"
      "clientRole": {"encodedKey":"d9df8bc78a0234ccc934a845c"}
   }
}

//POST update a simple client with id 21qds1231 using JSON
POST api/clients/21qds1231
{
    "client":{
      "firstName":"Max",
      "lastName":"Alexander",
      "middleName":"Frank",
      "homePhone":"56611235498",
      "emailAddress":"max.alexander@mambu.com",
      "mobilePhone1":"211111111",
      "gender":"MALE"
   }
} 

//POST create a client with grouped custom fields and fill in info into 'Call_Summary_Clients' field from the group, using JSON
POST /api/clients
{
   "client":{
      "firstName":"John",
      "lastName":"Doe",
      "middleName":"MiddleName",
      "homePhone":"56611235498",
      "emailAddress":"john.doe@mambu.com",
      "mobilePhone1":"211111111",
      "gender":"MALE",
      "birthDate":"1990-07-08T00:00:00+0200"
   },
   "customInformation":[
      {
         "value":"1",
         "customFieldID":"Call_Summary_Clients",
         "customFieldSetGroupIndex" : "0"
      },
       {
         "value":"2",
         "customFieldID":"Call_Summary_Clients",
         "customFieldSetGroupIndex" : "1"
      }
    ]
} 

//POST update client with encodedKey '8a512236413395270141356dbc9f0025' using JSON and remove all custom fields, addresses and ID Documents
POST api/clients/8a512236413395270141356dbc9f0025
{
   "client":{
      "firstName":"Max",
      "lastName":"Alexander",
      "middleName":"Frank",
      "homePhone":"56611235498",
      "emailAddress":"max.alexander@mambu.com",
      "mobilePhone1":"211111111",
      "gender":"MALE"
   },
   "idDocuments":[ ],
   "addresses":[ ],
   "customInformation":[ ]
} 

//POST update a client using JSON and update custom fields, addresses and ID Documents
POST api/clients/8a512236413395270141356dbc9f0025
{
   "client":{
      "firstName":"Max",
      "lastName":"Alexander",
      "middleName":"Frank",
      "homePhone":"56611235498",
      "emailAddress":"max.alexander@mambu.com",
      "mobilePhone1":"211111111",
      "gender":"MALE"
   },
   "idDocuments":[
      {
         "documentType":"CI",
         "documentId":"23453",
         "issuingAuthority":"Police",
         "validUntil":"2014-09-30T00:00:00+0000"
         "identificationDocumentTemplateKey":"9b0a97094b4cd73f014b5f5ef0e811d2"
      },
      {
         "documentType":"Passport",
         "documentId":"sss332",
         "issuingAuthority":"Passport Agency",
         "validUntil":"2014-09-30T00:00:00+0000"
         "identificationDocumentTemplateKey":"2a0a00a24b4ce72a025c4afefce821e9"
      }
   ],
   "addresses":[
      {
         "line1":"8 Howling Lane",
         "line2":"Hackney",
         "city":"London",
         "region":"London",
         "postcode":"1234554321",
         "country":"United Kingdom"
      }
   ],
   "customInformation":[
      {
         "value":"1",
         "customFieldID":"Family_Members"
      },
      {
         "value":"TRUE",
         "customFieldID":"Has_children"
      },
      {
         "value":"Some Studies",
         "customFieldID":"Studies"
      }
   ]
} 

 //post a client's photo
POST /api/clients/131241/documents/PROFILE_PICTURE
{
    "document": {
        "documentHolderKey": "88af35b9ca0933ec72",
        "documentHolderType": "CLIENT",
        "name": "picture",
        "type": "jpg"
        },
    "documentContent": "KFJGFirnb9FKFLkflkjfgJFLKJG249LKB"
    }
}

//post a client's signature
POST /api/clients/131241/documents/SIGNATURE
{
    "document": {
        "documentHolderKey": "88af35b9ca0933ec72",
        "documentHolderType": "CLIENT",
        "name": "picture",
        "type": "jpg"
        },
    "documentContent": "KFJGFirnb9FKFLkflkjfgJFLKJG249LKB"
    }
}

Response

A 201 Response is returned if the client was successfully created/updated. The response Location header is set to the client id and the created/updated client is also returned

PATCH Client

Core client fields can updated using the PATCH method. Normal validations and constraints as required in the POST method will be applied.

Parameters for PATCH method for client

state Allowed states: BLACKLISTED, REJECTED, EXITED, INACTIVE(approved), PENDING_APPROVAL(undo approval). It does not accept NULL values.
assignedBranchKey The id of the branch that the client is assigned to
assignedCentreKey The id of the centre that the client is assigned to
assignedUserKey The id of the credit officer that the client is assigned to

Usage Example

//Change the client state to BLACKLISTED
PATCH /api/clients/1332214
'{
   "client":
      {
         "state":"BLACKLISTED"
      }
}'
//Change the client assignments
PATCH /api/clients/1332214
'{
   "client":
      {
         "assignedBranchKey":"402832b43809601c01380963908b0009",
         "assignedCentreKey":"8a33ae49441c4fe101441c713b3a0010",
         "assignedUserKey":"402832b43809601c013809601f9d0002"
      }
}'

DELETE Client

Allows deleting clients directly by a client ID/key.
Usage examples

//delete client using client id
DELETE /api/clients/8

//get the basic clients details using client encoded key
DELETE /api/clients/8a27a878491d417601491d48203100d9

Samples responses:


//success response
{"returnCode":0,"returnStatus":"SUCCESS"}

PATCH Client Custom Field Values

Custom field values for a client can be added/edited using PATCH method. The new custom field value is validated based on the custom field type defined in the Custom Field.

Parameters for PATCH custom fields method for client

value New value for the custom field. Required.
customFieldID The id of the custom field to be edited. Required when editing multiple.
customFieldSetGroupIndex The index of the custom field set to be edited. If it isn't provided, a new set is added.

Usage Example

// Update the custom field value to "10" based on the client id(abc123) and on the custom field id(family_members)
PATCH '{ "value": "10" }' /api/clients/abc123/custominformation/family_members

// Update the custom field value to "2012-10-10" based on the client key(40288a134887e7e9014887f0eb720003) and on the custom field key(8a27a878491d417601491d48203100d9)
PATCH '{ "value": "2012-10-10" }' /api/clients/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9

// Update(add / edit) multiple grouped and / or standard fields from different groups for the client with the id 1111. 
// For a grouped custom field, if customFieldSetGroupIndex is present, 
// value is updated, if is missing, a new group is created. 
PATCH '{
  "customInformation": [
    {
      "customFieldID" : "IBAN",
      "value" : "DE123456789121243546783"
    },
    {
      "customFieldID" : "BIC",
      "value" : "1234566441",
      "customFieldSetGroupIndex" : "0"
    },
    {
      "customFieldID" : "BANK_ACCOUNT_TYPE",
      "value" : "Current Account",
      "customFieldSetGroupIndex" : "1"
    }
  ]
}' /api/clients/1111/custominformation/

Response

A 200 Response is returned if the client custom field value was successfully created/updated.

GET Client Custom Field Values

Allows retrieving a custom field value for a given client directly by the ID/key of the client and the ID/key of the custom field.

Usage Example

//get the custom field value of the custom field with the ID "family_members" for the client having ID "abc123"
GET /api/clients/abc123/custominformation/family_members
//get the custom field value of the custom field with the encoded key "8a8080a254a98efe0154a99ad86f00ef" for the client having key "8a8080a254a98efe0154a99ad8c400f6"
GET /api/clients/8a8080a254a98efe0154a99ad8c400f6/custominformation/8a8080a254a98efe0154a99ad86f00ef

Response

//response for a single custom field
[
  {
    "encodedKey": "8a8080a254a98efe0154a99ad9d301be",
    "parentKey": "8a8080a254a98efe0154a99ad8c400f6",
    "customFieldKey": "8a8080a254a98efe0154a99ad86f00ef",
    "customField": {
      "encodedKey": "8a8080a254a98efe0154a99ad86f00ef",
      "id": "Position_Clients",
      "creationDate": "2016-05-18T14:39:13+0000",
      "lastModifiedDate": "2016-05-18T14:40:19+0000",
      "name": "Position",
      "type": "CLIENT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254a98efe0154a99ad84200ee",
        "name": "Custom Fields",
        "createdDate": "2016-05-13T10:12:58+0000",
        "indexInList": 0,
        "type": "CLIENT_INFO",
        "usage": "SINGLE"
      },
      "indexInList": 3,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87200f0",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87300f1",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "Promotions manager",
    "indexInList": 0,
    "customFieldID": "Position_Clients",
    "customFieldSetGroupIndex": -1
  }
]
//response for a grouped custom field
[
  {
    "encodedKey": "8a8080a254c4397d0154c450f88d0034",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "CLIENT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "CLIENT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "111",
    "indexInList": 0,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 0
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410037",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "CLIENT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "CLIENT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "222",
    "indexInList": 2,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 1
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410039",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "CLIENT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "CLIENT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "333",
    "indexInList": 4,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 2
  }
]

DELETE Client Custom Field Values

Specific custom field values for a client can be deleted based on client id and custom field id.

Usage Example


// DELETE the custom field value based on the client id(abc123) and on the custom field id(family_members)
DELETE /api/clients/abc123/custominformation/family_members

// DELETE the custom field value based on the client key(40288a134887e7e9014887f0eb720003) and on the custom field key(8a27a878491d417601491d48203100d9)
DELETE /api/clients/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9

DELETE /api/clients/121357/documents/PROFILE_PICTURE

DELETE /api/clients/121357/documents/SIGNATURE

Response

A 200 Response is returned if the client custom field value was successfully deleted.

POST Search

Allows to retrieve clients using dynamic custom filters.

Parameters

Parameter Value
filterConstraints A JSON array of constraints.
filterSelection The field on which the constraint will be applied. Available client filter selections can be found bellow.
filterElement The constraint operator. Available filter elements can be found bellow.
value The constraint value. Required for filter elements with one or two values.
secondValue The constraint second value. Required for filter elements with two values.
dataItemType The entity where the field on which to apply the constraint is located. If the field is located in the same entity with the entity being searched, this field is optional.

Available client filter values

Filter Selection Parameter Data Type
CREDIT_OFFICER_KEY KEY
CLIENT_ROLE_KEY KEY
BRANCH_KEY KEY
CENTRE_KEY KEY
GROUP_KEY KEY
ENCODED_KEY KEY
FULL_NAME STRING
FIRST_NAME STRING
MIDDLE_NAME STRING
LAST_NAME STRING
CREATION_DATE DATE_UTC
LAST_MODIFIED_DATE DATE_UTC
ID STRING
DEPOSITS_BALANCE MONEY
LOANS_BALANCE MONEY
PENDING_LOAN_AMOUNT MONEY
APPROVED_LOAN_AMOUNT MONEY
TOTAL_BALANCE MONEY
TOTAL_DUE MONEY
HOME_PHONE_NUMBER STRING
MOBILE_PHONE_NUMBER STRING
EMAIL_ADDRESS STRING
CLIENT_ADDRESS STRING
BIRTHDATE DATE
GENDER ENUM
LOAN_CYCLE NUMBER
GROUP_LOAN_CYCLE NUMBER
CLIENT_STATE ENUM
PORTAL_STATE ENUM
PREFERRED_LANGUAGE ENUM
GROUP_ID STRING

Available filter elements

Filter Element Number Of affected values Available for
EQUALS ONE_VALUE BIG_DECIMAL,BOOLEAN,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY
MORE_THAN ONE_VALUE BIG_DECIMAL,NUMBER,MONEY
LESS_THAN ONE_VALUE BIG_DECIMAL,NUMBER,MONEY
BETWEEN TWO_VALUES BIG_DECIMAL,NUMBER,MONEY,DATE,DATE_UTC
ON ONE_VALUE DATE,DATE_UTC
AFTER ONE_VALUE DATE,DATE_UTC
BEFORE ONE_VALUE DATE,DATE_UTC
STARTS_WITH ONE_VALUE STRING
IN LIST ENUM,KEY
TODAY NO_VALUE DATE,DATE_UTC
THIS_WEEK NO_VALUE DATE,DATE_UTC
THIS_MONTH NO_VALUE DATE,DATE_UTC
THIS_YEAR NO_VALUE DATE,DATE_UTC
LAST_DAYS ONE_VALUE DATE,DATE_UTC
EMPTY NO_VALUE BIG_DECIMAL,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY,DATE,DATE_UTC
NOT_EMPTY NO_VALUE BIG_DECIMAL,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY,DATE,DATE_UTC

Usage examples

// get all clients born in a specific date range
POST /api/clients/search
{
   "filterConstraints":[
      {
         "filterSelection":"BIRTHDATE",
         "filterElement":"BETWEEN",
         "value":"2015-01-01",
         "secondValue":"2015-06-20"
      }
   ]
}
// get all male clients
POST /api/clients/search
{
   "filterConstraints":[
      {
         "filterSelection":"GENDER",
         "filterElement":"EQUALS",
         "value":"MALE"
      }
   ]
}
// get all clients created this month
POST /api/clients/search
{
   "filterConstraints":[
      {
         "filterSelection":"CREATION_DATE",
         "filterElement":"THIS_MONTH"
      }
   ]
}

Response

The clients that match the search will be returned
support@mambu.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete