Developer Center

Branches API

Last Updated: Feb 20, 2017 04:18PM CET

URL

/api/branches
/api/branches/{id}
/api/branches/{id}/custominformation/{customFieldId}

Description

Allows you to retrieve branches which are being used by an organization. For information about custom fields and custom fields sets in branches see Custom Fields API.

Methods

GET Branches

Allows retrieving branches via a paginated list or by using the branch id/key. While using the branch id/key the full details of the branch can be retreived(address, custom fields, holidays). The custom field values can be changed using patch or delete methods.

Parameters

fullDetails Whether to load all the nested fields for the branch as well (true or false)

Usage examples

//get up to 100 branches for the organization
GET /api/branches?limit=100&offset=0

//get the branch by id
GET /api/branches/demoBranchId

//get the branch by encoded key
GET /api/branches/402832b43809601c01380963908b0009

//get the branch by id with full details
GET /api/branches/demoBranchId?fulldetails=true


Samples responses:

//response containing the branches in the system
[  
   {  
      "encodedKey":"402832b43809601c01380963908b0009",
      "id":"2",
      "creationDate":"2012-06-20T12:15:16+0200",
      "lastModifiedDate":"2012-06-20T12:15:16+0200",
      "name":"Matola City"
   },
   {  
      "encodedKey":"402832b43809601c01380963907c0008",
      "id":"demoBranchId",
      "creationDate":"2012-06-20T12:15:16+0200",
      "lastModifiedDate":"2012-06-20T12:15:16+0200",
      "name":"Maputo Downtown"
   }
]

//response single branch fetch by id/key
{  
   "encodedKey":"402832b43809601c01380963908b0009",
   "id":"2",
   "creationDate":"2012-06-20T12:15:16+0200",
   "lastModifiedDate":"2012-06-20T12:15:16+0200",
   "name":"Matola City"
}

//response single branch with full details by id/key
{  
   "encodedKey":"8a33ae49441c4fe101441c713b36000e",
   "id":"2",
   "creationDate":"2014-02-10T15:36:26+0000",
   "lastModifiedDate":"2014-02-17T11:18:42+0000",
   "name":"Matola City",
   "phoneNumber":"",
   "emailAddress":"",
   "branchHolidays":[  
      {  
         "encodedKey":"8a54e5b4443e9c9401443fae924b0008",
         "keyId":31,
         "name":"branch_holiday",
         "dayOfMonth":17,
         "monthOfYear":2,
         "year":2014,
         "isAnnualyRecurring":true
      }
   ],
   "address":{  
      "encodedKey":"8a42711a4428c1f101442be406d30c25",
      "parentKey":"8a33ae49441c4fe101441c713b36000e",
      "line1":"dasda",
      "line2":"",
      "city":"",
      "region":"",
      "postcode":"",
      "country":"",
      "indexInList":-1
   },
   "customFieldValues":[  
      {  
         "encodedKey":"8a42711a4428c1f101442be406d20c24",
         "parentKey":"8a33ae49441c4fe101441c713b36000e",
         "customFieldKey":"8a33ae49441c4fe101441c7156c20358",
         "customField":{  
            "encodedKey":"8a33ae49441c4fe101441c7156c20358",
            "id":"Clients_Branches",
            "name":"Clients",
            "type":"BRANCH_INFO",
            "dataType":"STRING",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "customFieldSet":{  
               "encodedKey":"8a33ae49441c4fe101441c71568f034c",
               "name":"Branch Organization",
               "createdDate":"2014-02-10T15:36:33+0000",
               "indexInList":0,
               "type":"BRANCH_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"dadsds",
         "indexInList":-1
      },
      {  
         "encodedKey":"8a54e5b4443e9c9401443f91c7a20003",
         "parentKey":"8a33ae49441c4fe101441c713b36000e",
         "customFieldKey":"8a33ae49441c4fe101441c7156c5035a",
         "customField":{  
            "encodedKey":"8a33ae49441c4fe101441c7156c5035a",
            "id":"Organization_Staff_Branches",
            "name":"Organization Staff",
            "type":"BRANCH_INFO",
            "dataType":"NUMBER",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "customFieldSet":{  
               "encodedKey":"8a33ae49441c4fe101441c71568f034c",
               "name":"Branch Organization",
               "createdDate":"2014-02-10T15:36:33+0000",
               "indexInList":0,
               "type":"BRANCH_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"4",
         "indexInList":-1
      },
      {  
         "encodedKey":"8a54e5b4443e9c9401443f91c7b90004",
         "parentKey":"8a33ae49441c4fe101441c713b36000e",
         "customFieldKey":"8a33ae49441c4fe101441c7156c30359",
         "customField":{  
            "encodedKey":"8a33ae49441c4fe101441c7156c30359",
            "id":"Province_Branches",
            "name":"Province",
            "type":"BRANCH_INFO",
            "dataType":"SELECTION",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "values":[  
               "Catamarca",
               "Chaco",
               "Jujuy"
            ],
            "amounts":{  
               "Jujuy":"10",
               "Chaco":"1",
               "Catamarca":"0"
            },
            "customFieldSet":{  
               "encodedKey":"8a33ae49441c4fe101441c71569a034d",
               "name":"Province",
               "createdDate":"2014-02-10T15:36:33+0000",
               "indexInList":1,
               "type":"BRANCH_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"Catamarca",
         "amount":"0",
         "indexInList":-1
      },
      {  
         "encodedKey":"8a54e5b4443e9c9401443f91c7b90005",
         "parentKey":"8a33ae49441c4fe101441c713b36000e",
         "customFieldKey":"8a33ae49441c4fe101441c7156c7035b",
         "customField":{  
            "encodedKey":"8a33ae49441c4fe101441c7156c7035b",
            "id":"Outside_of_province_Branches",
            "name":"Outside of province",
            "type":"BRANCH_INFO",
            "dataType":"CHECKBOX",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "customFieldSet":{  
               "encodedKey":"8a33ae49441c4fe101441c71569a034d",
               "name":"Province",
               "createdDate":"2014-02-10T15:36:33+0000",
               "indexInList":1,
               "type":"BRANCH_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"FALSE",
         "indexInList":-1
      }
   ]
}

PATCH Branch Custom Field Values

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

Parameters for PATCH custom fields method for branch

value New value for 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 branch id(abc123) and on the custom field id(members)
PATCH '{ "value": "10" }' /api/branches/abc123/custominformation/members

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

// Update(add / edit) multiple grouped and / or standard fields from different groups for the branch 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/branches/111/custominformation/

Response

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

GET Client Custom Field Values

Allows retrieving a custom field value for a given branch directly by the ID/key of the branch 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 branch having ID "abc123"
GET /api/branches/abc123/custominformation/family_members
//get the custom field value of the custom field with the encoded key "8a8080a254a98efe0154a99ad86f00ef" for the branch having key "8a8080a254a98efe0154a99ad8c400f6"
GET /api/branches/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": "BRANCH_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": "BRANCH_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": "BRANCH_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": "BRANCH_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": "BRANCH_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": "BRANCH_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": "BRANCH_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": "BRANCH_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 Branch Custom Field Values

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

Usage Example

// DELETE the custom field value based on the branch id(abc123) and on the custom field id(members)
DELETE /api/branches/abc123/custominformation/members

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

Response

A 200 Response is returned if the branch custom field value was successfully deleted.
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