General
Companies
General Companies API documentation
Please note this page is under construction
Introduction
The companies API call is used to manage leads 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 /companies/list |
JSON Body:
{
"pagination": {
"perpage": 100,
"page": 1
},
"sort": {
"field": "updated_at",
"sort": "desc"
},
"query": {
"generalSearch": "Inc Corp"
}
}
All body parameters are optional.
The generalSearch parameter can be used to search records by company name, email, phone, customer/member number or registration number.
JSON Response:
{
"meta": {
"page": 1,
"pages": 1,
"perpage": 100,
"total": 25,
"sort": "desc",
"field": "updated_at"
},
"data": [
{
"id": "6d6be205-b1da-4820-9cc8-e956ef070737",
"name": "New Inc Corp",
"trading_as": "New Inc Corp",
"registration_number": "20142/182645/07",
"member_number": "MEM123456",
"email": "newinco@corp.com",
"email_score": 96,
"contact": "+2712345678",
"mobile": "+27810445467",
"fax": "+27123456789",
"website": "https://mycompany.com",
"date_closed": null,
"postal_line_1": "123 Park Street",
"postal_line_2": "Brooklyn",
"postal_line_3": "Pretoria",
"postal_line_4": "Gauteng",
"postal_code": "0081",
"physical_line_1": "123 Park Street",
"physical_line_2": "Brooklyn",
"physical_line_3": "Pretoria",
"physical_line_4": "Gauteng",
"physical_code": "0081",
"is_taxable": true,
"is_marketing_sms": true,
"is_marketing_whatsapp": true,
"is_marketing_email": true,
"is_marketing_phone": true,
"is_active": true,
"tax_reference": "0123456789",
"deal_value": 25457.54,
"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": 57,
"total_failed_transactions": 4,
"total_subscriptions": 2,
"total_subscriptions_products": 3,
"total_active_subscriptions_products": 2,
"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",
"referred_by": "Marcus Black",
"owner_admins": ["Henco Smith"],
"call_last_contacted_by_agents_id": "21b27320-fcaa-4e23-af1f-72365c471640",
"call_last_contacted_by_agents_title": "Martha Smith",
"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",
"source_of_record_id": "69689662-deb4-4513-9940-94afa442f720",
"source_of_record_title": "Added",
"tax_name": "VAT",
"tax_value": "15.00",
"type_title": "Private Limited Company",
"country_title": "South Africa",
"region_title": "Gauteng",
"branch_title": "Head Office",
"branches_regions_title": "Sandton",
"branches_regions_id": "c07cca49-af09-4d0d-9755-4876c67e3f88",
"agent_title": "Marie Jue",
"image": "https://images.com/123",
"social_facebook": "https://facebook.com/123",
"social_linkedin": "https://linkedin.com/123",
"social_instagram": "https://instagram.com/123",
"social_twitter": "https://x.com/123",
"social_pinterest": "https://pinterest.com/123",
"social_blog": "https://blog.com/123",
"social_whatsapp": "+27800000008",
"social_telegram": "+27800000006",
"created_at": "2022-06-23T12:29:33.305Z",
"custom_fields": {
"Category": "Small",
"Date Renew License": "2025-01-01",
}
},
...
]
}
All lookup values can be found under: Lookups API
Create Records
This API call will create a single record.
| Path |
|---|
POST /companies/create |
JSON Body:
{
"type_lookups_id": "f6cf9a30-b302-4ed9-a89c-1ccbe9889358",
"name": "New Inc Corp",
"trading_as": "New Inc Corp",
"registration_number": "20142/182645/07",
"member_number": "MEM123456",
"email": "newinco@corp.com",
"contact": "+2712345678",
"is_active":true,
"is_marketing_sms":true,
"is_marketing_whatsapp":true,
"is_marketing_email":true,
"is_marketing_phone":true,
"custom_fields": {
"Category": "Small",
"Date Renew License": "2025-01-01",
},
...
}
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 /companies/update/{record_id} |
JSON Body:
{
"type_lookups_id": "f6cf9a30-b302-4ed9-a89c-1ccbe9889358",
"name": "New Inc Corp",
"trading_as": "New Inc Corp",
"registration_number": "20142/182645/07",
"member_number": "MEM123456",
"email": "newinco@corp.com",
"contact": "+2712345678",
"is_active":true,
"is_marketing_sms":true,
"is_marketing_whatsapp":true,
"is_marketing_email":true,
"is_marketing_phone":true,
"visible_to_lookups_id": "842e0539-3083-4e17-86c1-cf99e0243d24",
"owner_admins_ids": ["2fb28f67-a39a-4642-9ce2-473e75c248c9", "d2abe74e-a5a2-47ba-85a5-5b14450c4ea0"],
"custom_fields": {
"Category": "Small",
"Date Renew License": "2025-01-01",
},
...
}
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:
| Key | Title Case |
|---|---|
| agents_id | Agents Id |
| balance_open | Balance Open |
| balance_outstanding | Balance Outstanding |
| branches_id | Branches Id |
| contact | Contact |
| country_lookups_id | Country Lookups Id |
| custom_fields | Custom Fields |
| date_balance_open | Date Balance Open |
| date_closed | Date Closed |
| day_billing | Day Billing |
| deal_accounts_currencies_id | Deal Accounts Currencies Id |
| deal_expected_close_date | Deal Expected Close Date |
| deal_value | Deal Value |
| default_accounts_currencies_id | Default Accounts Currencies Id |
| default_accounts_tax_id | Default Accounts Tax Id |
| fax | Fax |
| image | Image URL |
| 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 |
| member_number | Member Number |
| mobile | Mobile |
| municipality_lookups_id | Municipality Lookups Id |
| name | Name |
| owner_admins_ids | Owner Admins Ids |
| 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 |
| registration_number | Registration Number |
| role_lookups_id | Role Lookups Id |
| social_facebook | Social Facebook |
| social_linkedin | Social Linkedin |
| social_instagram | Social Instagram |
| social_twitter | Social Twittter / X |
| social_pinterest | Social Pinterest |
| social_blog | Social Blog |
| social_whatsapp | Social WhatsApp |
| social_telegram | Social Telegram |
| source_of_record_lookups_id | Source Of Record |
| tax_reference | Tax Reference |
| trading_as | Trading As |
| type_lookups_id | Type Lookups Id |
| visible_to_lookups_id | Visible To Lookups Id |
| website | Website |
All lookup values can be found under: Lookups API