People - SwitchTransact Docs

Please note this page is under construction

Introduction

The people API call is used to manage leads/contacts or accounts records on SwitchTransact.

Unlike the Contact Centre API call these changes will not go through a Approval process.

List Records

This API call will list all the records.

Path
`POST` `/people/list`

JSON Body:

{
    "pagination": {
        "perpage": 100,
        "page": 1
    },
    "sort": {
        "field": "updated_at",
        "sort": "desc"
    },
    "query": {
        "generalSearch": "James"
    }
}

All body parameters are optional.

The generalSearch parameter can be used to search records by name, surname, email, phone, customer/member number or ID number.

JSON Response:

{
    "meta": {
        "page": 1,
        "pages": 1,
        "perpage": 100,
        "total": 25,
        "sort": "desc",
        "field": "updated_at"
    },
    "data": [
        {
            "id": "f14a389f-cfc3-4f4a-9d49-77c07310af6f",
            "name": "James",
            "middle_names": "Jonathan Henry",
            "surname": "May",
            "initials": "J",
            "nickname": "James",
            "email": "james@may",
            "id_number": "801234567891",
            "id_number_type_id": "147c8cdb-3bb1-4920-8e24-6a02d8f50a21",
            "id_number_type_title": "SA ID Number",
            "member_number": "MEM1234",
            "contact_cell": "+2712345678",
            "contact_work": "",
            "contact_home": "",
            "title_id": "56926d84-6039-4f32-b46a-73d2d5d7f7c5",
            "title_title": "Mr",
            "gender_id": "331699c7-6c54-46dd-b80c-7cfb20bd8200",
            "gender_title": "Male",
            "language_id": "33306a46-837b-4ee5-a7ab-c76dec881578",
            "language_title": "English",
            "marital_id": "3685f213-2357-4ad4-b81e-d14fb227bc18",
            "marital_title": "Married",
            "day_salary": 10,
            "is_active": true,
            "date_birth": "1980-04-04T00:00:00.000Z",
            "date_joined": "2006-01-07T00:00:00.000Z",
            "date_deceased": null,
            "age_join": 39,
            "photo": "https://images.com/123",
            "is_taxable": false,
            "date_balance_open": "2006-01-01T00:00:00.000Z",
            "balance_open": 576.24,
            "is_marketing_sms": true,
            "is_marketing_whatsapp": false,
            "is_marketing_email": true,
            "is_marketing_phone": true,
            "physical_line_1": "123 Park Street",
            "physical_line_2": "Brooklyn",
            "physical_line_3": "Pretoria",
            "physical_line_4": "Gauteng",
            "physical_code": "0081",
            "postal_line_1": "123 Park Street",
            "postal_line_2": "Brooklyn",
            "postal_line_3": "Pretoria",
            "postal_line_4": "Gauteng",
            "postal_code": "0081",
            "tax_reference": "0123456789",
            "deal_value": 10195.45,
            "deal_accounts_currencies_id": "f34eb5cc-f6f7-4e9a-972e-bb57bff6c061",
            "deal_accounts_currencies_title": "ZAR",
            "deal_expected_close_date": "2030-01-01T00:00:00.000Z",
            "is_blacklisted": false,
            "total_successful_transactions": 4,
            "total_failed_transactions": 1,
            "total_subscriptions": 1,
            "total_subscriptions_products": 1,
            "total_active_subscriptions_products": 1,
            "call_last_contacted": "2024-03-25T15:45:54.845Z",
            "date_phone_invalid": null,
            "date_lead_conversion": "2005-12-26T00:00:00.000Z",
            "date_paid_up": "2024-05-01T00:00:00.000Z",
            "address_details_changed_at": "2024-03-16T00:00:00.000Z",
            "contact_details_changed_at": "2024-03-08T00:00:00.000Z",
            "last_engagement_at": "2024-03-26T12:05:15.845Z",
            "status_changed_at": "2024-04-01T04:16:55.551Z",
            "date_id_number_verify": "2024-03-22T15:43:12.541Z",
            "credit_score_cpa": 670,
            "credit_score_nlr": 629,
            "referred_by": "Marcus Black",
            "owner_admins": ["Henco Smith"],
            "companies_id": "e7cadb01-0979-4e18-b591-37b8f496422c",
            "companies_name": "Cargo Swift",
            "companies_trading_as": "Cargo Swift Ltd",
            "call_last_contacted_by_agents_id": "21b27320-fcaa-4e23-af1f-72365c471640",
            "call_last_contacted_by_agents_title": "Martha Smith",
            "country_id": "42729507-5a0b-4ded-a6e4-014d3276a005",
            "country_title": "South Africa",
            "region_id": "3b39fec9-86b9-408c-b60a-1a0769db14bb",
            "region_title": "Gauteng",
            "branch_id": "22f41ab2-3426-40e6-9ca6-5c1852b0e930",
            "branch_title": "Head Office",
            "branches_regions_id": "c07cca49-af09-4d0d-9755-4876c67e3f88",
            "branches_regions_title": "Sandton",
            "agents_id": "82fad418-4a43-4726-8a6b-022fc0622e6e",
            "agents_name": "Call Centre Name",
            "visible_to_id": "842e0539-3083-4e17-86c1-cf99e0243d24",
            "visible_to_title": "Record Owner(s)",
            "municipality_id": "be7b0599-321c-43d1-85f5-c4d2d6808969",
            "municipality_title": "City of Johannesburg",
            "job_id": "7148c85b-b83a-4bc9-8a35-d93e9029b979",
            "job_title": "Business Owner",
            "source_of_record_id": "69689662-deb4-4513-9940-94afa442f720",
            "source_of_record_title": "Added",
            "updated_at": "2024-04-05T05:15:04.454Z",
            "created_at": "2004-10-31T22:00:00.000Z",
            "custom_fields": {
                "Alternative Mobile Number": 0721234567,
                "Max Payment": 50.25,
                "Out of Country": true,
                "List of Children": ["Ruben", "James"]
            }
        },
        ...
    ]
}

All lookup values can be found under: Lookups API

Create Records

This API call will create a single record.

Path
`POST` `/people/create`

JSON Body:

{
    "name":"James",
    "surname":"May",
    "id_number":"801234567891",
    "email":"james@may.com",
    "contact_cell":"270123456789",
    "date_birth":"1980-04-01",
    "day_salary":"1",
    "custom_fields": { 
        "Alternative Mobile Number": 0721234567,
        "Max Payment": 50.25,
        "Out of Country": true,
        "List of Children": ["Ruben", "James"]
    },
    ...
}

All body parameters are optional and shown under Body Fields.

Successful response:

{
  "record": {
    ...record object
  },
  "publicId": "b9daf9a724c305ebec2b0b2c763b......bd2dee8a8b0ca6adfbc5a753da0",
}

Error response:

{
  "status": false,
  "error": "Error message",
  "errors": {
    ...Validation error object
  }
}

Update Records

This API call will update a single record.

Path
`POST` `/people/update/{record_id}`

JSON Body:

{
    "name":"James",
    "surname":"May",
    "id_number":"801234567891",
    "email":"james@may.com",
    "contact_cell":"270123456789",
    "date_birth":"1980-04-01",
    "day_salary":"1",
    "visible_to_lookups_id": "842e0539-3083-4e17-86c1-cf99e0243d24",
    "owner_admins_ids": ["2fb28f67-a39a-4642-9ce2-473e75c248c9", "d2abe74e-a5a2-47ba-85a5-5b14450c4ea0"],
    "custom_fields": { 
        "Alternative Mobile Number": 0721234567,
        "Max Payment": 50.25,
        "Out of Country": true,
        "List of Children": ["Ruben", "James"]
    },
    ...
}

All body parameters are optional and shown under Body Fields.

Successful response:

{
  "record": {
    ...record object
  },
  "publicId": "b9daf9a724c305ebec2b0b2c763b......bd2dee8a8b0ca6adfbc5a753da0",
}

Error response:

{
  "status": false,
  "error": "Error message",
  "errors": {
    ...Validation error object
  }
}

Body Fields

Below are all the fields for a record:

Field	Name
age_join	Age Join
agents_id	Agents Id
balance_open	Balance Open
branches_id	Branches Id
campaigns_ids	Campaigns Ids
companies_id	Companies Id
custom_fields	Custom Fields
contact_cell	Contact Cell
contact_home	Contact Home
contact_work	Contact Work
country_lookups_id	Country Lookups Id
date_balance_open	Date Balance Open
date_birth	Date Birth
date_deceased	Date Deceased
date_joined	Date Joined
date_rejoined	Date Rejoined
date_resigned	Date Resigned
day_salary	Day Salary
deal_accounts_currencies_id	Deal Accounts Currencies Id
deal_expected_close_date	Deal Expected Close Date
deal_value	Deal Value
email	Email
gender_lookups_id	Gender Lookups Id
id_number	ID / Passport Number
id_number_type_lookups_id	ID Number Type Lookups Id
initials	Initials
is_active	Is Active
is_blacklisted	Is Blacklisted
is_marketing_email	Is Marketing Email
is_marketing_phone	Is Marketing Phone
is_marketing_sms	Is Marketing SMS
is_marketing_whatsapp	Is Marketing WhatsApp
is_taxable	Is Taxable
job_lookups_id	Job Lookups Id
language_lookups_id	Language Lookups Id
lists_ids	Lists Ids
marital_lookups_id	Marital Lookups Id
member_number	Member Number
middle_names	Middle Names
municipality_lookups_id	Municipality Lookups Id
name	Name
nickname	Nickname
owner_admins_ids	Owner Admin Ids
photo	Photo URL
physical_code	Physical Code
physical_line_1	Physical Line 1
physical_line_2	Physical Line 2
physical_line_3	Physical Line 3
physical_line_4	Physical Line 4
postal_code	Postal Code
postal_line_1	Postal Line 1
postal_line_2	Postal Line 2
postal_line_3	Postal Line 3
postal_line_4	Postal Line 4
referred_by	Referred By
region_lookups_id	Region Lookups Id
role_lookups_id	Role Lookups Id
surname	Surname
tax_reference	Tax Reference
title_lookups_id	Title Lookups Id
visible_to_lookups_id	Visible To Lookups Id

All lookup values can be found under: Lookups API

Verify

General Verify API documentation

Companies

General Companies API documentation