Companies

Account Summary

This API call will return summary data related to companies loaded.

Path
`/workflow/company/details`

Request (POST)

Any of the following fields can be sent

Field name	Data type	Description
company_name	string	Company name. Does an approximate match e.g. you can search for ‘my co’ and it would return ‘my company’ for example.
registration_number	string	Company registration number
id	uuid	Database record id, in the workflow
record	boolean	If true show record section
subscriptions	boolean	If true show subscriptions section
bank_accounts	boolean	If true show bank_accounts section
transactions	boolean	If true show transactions section

Response (JSON)

Data is returned as a JSON object in the following format with multiple sections:

{
  "record": {
    "registration_number": 12345678,
    ......
  },
  "subscriptions": [{
    "date_start": "2020-03-12",
    ......
  }, ...],
  "bank_accounts": [{
    "accounts_holder": "J Smith",
    ......
  }, ...],
  "transactions": [{
    "transaction_number": "2865fca2-db87-4e37-8dd3-c350cd639a5c",
    ......
  }, ...],
}

Record section
Field name
Data type	Description
member_number	number	Membership number
registration_number	number	Company registration number
name	string	Name of the company
email	string	Email
country	string	Country the person resides in
region	string	province/state associated with above country
municipality	string	Municipality associated with the region
trading_as	string	Company registered trading name
contact	string	Contact number for the company
mobile	string	Mobile number for the company
fax	string	Fax number for the company
website	string	Company website address
balance_open	number	Journal opening balance
is_taxable	boolean	If the company is taxable or not
default_accounts_tax_id	string	Default account tax ID
day_billing	number	Default billing day for the company
tax_reference	string	Tax reference
description	string	Description associated with the company
social_facebook	string	Facebook URL
social_linkedin	string	Linkedin URL
social_instagram	string	Instagram URL
social_twitter	string	Twitter URL
social_pinterest	string	Pinterest URL
social_blog	string	Blog URL
social_whatsapp	string	Whatsapp number
social_telegram	string	Telegram number
web_referrer	string	Web referrer for this record
utm_campaign	string	UTM campaign parameter
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_content	string	UTM content parameter
utm_term	string	UTM term parameter
branch	string	Branch account was recruited at
agent	string	Agent who recruited account
physical_line_1	string	Physical address line 1
physical_line_2	string	Physical address line 2
physical_line_3	string	Physical address line 3
physical_line_4	string	Physical address line 4
physical_code	number	Physical postal code
postal_line_1	string	Postal address line 1
postal_line_2	string	Postal address line 2
postal_line_3	string	Postal address line 3
postal_line_4	string	Postal address line 4
postal_code	string	Postal code
is_marketing_sms	boolean	Can send sms marketing
is_marketing_whatsapp	boolean	Can send WhatsApp marketing
is_marketing_email	boolean	Can send email marketing
is_marketing_phone	boolean	Can send phone marketing
is_active	boolean	Is user an active member
company_type	string	Company type e.g. Public Limited Company
currency	string	Currency for the account e.g. ZAR
created_at	timestamp	When record was created
updated_at	timestamp	When record was updated
date_closed	date	Date company closed
date_balance_open	date	Date associated with journal opening balance
date_expire	date	Date company record became invalid
contact_name	string	Contact person name
contact_surname	string	Contact person surname
contact_title	string	Contact person title
language	string	Language
custom_fields	object	Optional custom fields associated with the record
branches_regions_title	string	Region associated with the branch
owner_admins	array	List of admin owners related to this record
visible_to_title	string	Visibility group of the record
deal_value	number	How much the deal is worth
deal_accounts_currencies_title	string	Currency associated with the deal value
deal_expected_close_date	date	When the deal is expected to close
is_blacklisted	boolean	Has this company been flagged as blacklisted
total_successful_transactions	number	Total number of successful transactions for this record
total_failed_transactions	number	Total number of failed transactions for this record
total_subscriptions	number	Total number of subscriptions associated with the record
total_subscriptions_products	number	Total number of subscription products associated with the record
total_active_subscriptions_products	number	Total number of active subscription products associated with the record
call_last_contacted_by_agents_title	string	Agent that last contacted the company by call
call_last_contacted	date	Date when last the company was contacted via call
date_phone_invalid	date	Date when the phone number was deemed invalid
date_lead_conversion	date	Date when the company was converted from a lead to an account
date_paid_up	date	Date until when the company is deemed to be paid up
address_details_changed_at	date	Date when the address details of the company was changed
contact_details_changed_at	date	Date when the contact details of the company was changed
last_engagement_at	date	Date when the company was last engaged with
status_changed_at	date	Date when the status of the company was last changed at
source_of_record_title	string	Source of the record e.g. API
referred_by	string	Who this company was referred by

Subscription section
Field name	Data type	Description
id	uuid	Unique ID
date_start	date	Date when subscription should start
date_end	date	Date when subscription should end. Blank will run forever.
bank_accounts_id	uuid	Bank account ID
products	array	List of products under this subscription
status	string	Active, Disputed, Disabled
Products (array of objects)
name	string	Name of product
amount	decimal	Amount ZAR of product
quantity	number	How many products were added
total	decimal	Total amount (amount * quantity)
branch	string	Branch product was recruited at
project	string	Project product was recruited under
agent	string	Agent who commissions should be paid out to
is_active	boolean	Is product under subscription active
created_at	timestamp	When product was created
updated_at	timestamp	When product was updated
reference_number	string	Reference provided when the API call was made

Bank accounts section
Field name	Data type	Description
id	uuid	Unique ID
account_holder	string	Name of bank account holder
account_number	string	Bank account number
account_type	string	Bank account type
bank	string	Bank name
branch_code	string	Bank branch code

Transactions section
Field name	Data type	Description
transaction_number	string	Unique number
amount	decimal	Amount collected
status	string	Paid, Transaction Accepted, Disputed, Unpaid
transaction_date	timestamp	When the transaction was processed
Items (array of objects)
name	string	Name of the product paid for.
unique_id	string	Unique ID associated with the product.
unit_name	string	Unit name of the product.
unit_label	string	Unit label of the product.
accounting_code	string	Accounting code associated with the product.
amount	decimal	Amount paid for.
reference_number	string	Reference number submitted on the initial workflow API call.

Add New Company

This API call provides for loading new companies onto the platform.

Path
`/workflow/company/create`

Request (POST) JSON Array

Field name	Data type	Required	Description
account_bank	string	C^{^[16]}, L	Bank name
account_branch_code	string	C^{^[12]}, L	Bank branch code
account_name	string	C^{^[13]}	Bank account holder name
account_number	string	C^{^[14]}	Bank account number
account_type	string	C^{^[15]}, L	Bank account type
agent	string	N, L	Agent who recruited account
balance_open	number	N	Journal opening balance in Rands
billing_day	number	C^{^[21]}	Day of debit order run for product (0 - 31). Only applicable if product details above have been provided.
branch	string	N, L	Branch account was recruited at
company_type	string	Y, L	Company type
contact_name	string	N	Name of Person to contact
contact_surname	string	N	Surname of Person to contact
contact_title	string	N, L	Title of Person to contact
contact	string	N	Contact number
country	string	N, L	Country the company is located in. Defaults to South Africa
custom_fields	Object	N	Object containing all optional custom fields returned by /lookups/custom_fields/people. E.g. { "spouse name": "Jane" }
date_balance_open	date	N	Date journal balance was opened
date_closed	date	N	Date company closed down
date_expire	date	N	Date company record became invalid
deal_accounts_currencies_id	string	N, L	Currency associated with the deal value
deal_expected_close_date	date	N	Expected closing date for the deal
deal_value	number	N	Amount expected to be gained from the deal e.g. 12500.0 ZAR
default_accounts_tax_id	string	N	Default account tax id
default_billing_day	string	C^{^[22]}	Default debit order day for the company
description	string	N	Company description
email	string	Y	Email
fax	string	N	Fax number
is_active	boolean	N	Company record is to be active. Defaults to true.
is_blacklisted	boolean	N	If this company has been flagged as blacklisted
is_marketing_email	boolean	N	Can send email marketing
is_marketing_phone	boolean	N	Can send phone marketing
is_marketing_sms	boolean	N	Can send sms marketing
is_marketing_whatsapp	boolean	N	Can send WhatsApp marketing
is_taxable	boolean	N	Company is taxable
language	string	N, L	Language (Same lookup as people)
mobile	string	N	Mobile number
municipality	String	N, L	Municipality associated with the region
name	string	Y	Company Name, must be unique
owner_admins_ids	array	N, L	Array of admin IDs to whom the record belongs
physical_code	number	N	Physical postal code
physical_line_1	string	N	Physical address line 1
physical_line_2	string	N	Physical address line 2
physical_line_3	string	N	Physical address line 3
physical_line_4	string	N	Physical address line 4
postal_code	string	N	Postal code
postal_line_1	string	N	Postal address line 1
postal_line_2	string	N	Postal address line 2
postal_line_3	string	N	Postal address line 3
postal_line_4	string	N	Postal address line 4
product_amount	Number	C^{^[18]}	Amount company is paying for the product in Cents e.g. 150 for R1.50
product_name	string	C^{^[17]}, L	Name of the product company is subscribed to
product_subscription_start_date	date	C^{^[20]}	When the subscription to the product is to start. If the product interval is greater than 1 month e.g. yearly, you may not pick a date that was already submitted in a batch. A good rule is that the starting date should be at least 12 days from now.
product_unit_name	string	C^{^[19]}, L	How frequently the product is billed
project	string	N, L	Project account was recruited under
reference_number	string	N	Custom reference number to tag the product with and display on workflow reporting.
region	string	N, L	Province/State the company is located in. Defaults to none/unknown
registration_number	string	N	Registration number
social_blog	string	N	Blog URL
social_facebook	string	N	Facebook URL
social_instagram	string	N	Instagram URL
social_linkedin	string	N	LinkedIn URL
social_pinterest	string	N	Pinterest URL
social_telegram	string	N	Telegram number
social_twitter	string	N	Twitter URL
social_whatsapp	string	N	WhatsApp number
tax_reference	string	N	Company tax reference
trading_as	string	Y	Registered trading name
utm_campaign	string	N	UTM campaign parameter
utm_content	string	N	UTM content parameter
utm_medium	string	N	UTM medium parameter
utm_source	string	N	UTM source parameter
utm_term	string	N	UTM term parameter
web_referrer	string	N	Web referrer URL
website	string	N	Website address
visible_to_lookups_id	string	N, L	Visibility group associated with the record

Response (JSON)

Data is returned as a JSON object in the following format with multiple sections:

{
  "Info": {
    "companies": {
      "accepted": 12345,
      "rejected": 678
    }
  },
  "accepted": [{...}],
  "rejected": [{
    "reasons": {  
      "account_number": {
        "message": "CDV check failed", 
        "rule": "CDV"
      }
    },
    "name": "xxxxxxxxxxxx",
    ...
  }, ...]
}

Info section
Sub-section	Field name	Data type	Description
companies	accepted	number	Number of records accepted
companies	rejected	number	Number of records rejected (See rejected section for more details)

Rejected section

Field name

Data type

Description

reasons

object

The reason why the record was rejected; some examples include:

Person already exists
Branch code format incorrect
Account number format incorrect
Account name format incorrect
CDV check failed

The reasons are given per input key that failed the validation e.g. "account_number".

name

string

Name associated with the rejected record (company name)

Accepted section
Field name	Data type	Description
unique_workflow_id	string	Unique ID associated with the submission. Can be used to cancel the item if it is still pending.
name	string	Name associated with the rejected record (company name)

Update Company

This API call provides for updating the details of existing companies on the platform.

Same conditions follow for bank account and product details as in creation i.e. if one bank account detail is to be updated all bank account details have to be provided.

Product details can only be provided when the company is currently inactive, in which case all their previously active subscriptions will be disabled before creating a new subscription (automatically reactivating them as well) or adding subscriptions to companies that currently have no active subscriptions. To add products to an existing subscription use the ‘add product’ API call.

Path
`/workflow/company/update`

Request (POST) JSON Array

Field name	Data type	Required	Description
account_bank	string	N, L	Bank name
account_branch_code	string	N, L	Bank branch code
account_name	string	N	Bank account holder name
account_number	string	N	Bank account number
account_type	string	N, L	Bank account type
agent	string	N, L	Agent who recruited account
balance_open	number	N	Journal opening balance in rands
billing_day	number	N	Day of debit order run for product (0 - 31). Only applicable if product details above have been provided.
branch	string	N, L	Branch account was recruited at
company_type	string	N, L	Company type
contact_name	string	N	Name of Person to contact
contact_surname	string	N	Surname of Person to contact
contact_title	string	N, L	Title of Person to contact
contact	string	N	Contact number
country	string	N, L	Country the company is located in. Defaults to South Africa
custom_fields	Object	N	Object containing all optional custom fields returned by /lookups/custom_fields/people. E.g. { "spouse name": "Jane" }
date_balance_open	date	N	Date journal balance was opened
date_closed	date	N	Date company closed down
date_expire	date	N	Date company record became invalid
deal_accounts_currencies_id	string	N, L	Currency associated with the deal value
deal_expected_close_date	date	N	Expected closing date for the deal
deal_value	number	N	Amount expected to be gained from the deal e.g. 12500.0 ZAR
default_accounts_tax_id	string	N	Default account tax id
default_billing_day	string	N	Default debit order day for the company
description	string	N	Company description
email	string	N	Email
fax	string	N	Fax number
is_active	boolean	N	Company record is to be active
is_blacklisted	boolean	N	If this company has been flagged as blacklisted
is_marketing_email	boolean	N	Can send email marketing
is_marketing_phone	boolean	N	Can send phone marketing
is_marketing_sms	boolean	N	Can send sms marketing
is_marketing_whatsapp	boolean	N	Can send WhatsApp marketing
is_taxable	boolean	N	Company is taxable
language	string	N, L	Language (Same lookup as people)
mobile	string	N	Mobile number
municipality	String	N, L	Municipality associated with the region
name	string	Y	Company Name. Must be unique and exist in the DB. Name is case insensitive but additional characters would affect the result. ‘MY COMPANY’ is the same as ‘My Company’ but ‘My Company LTD’ would not be found for example. Use the ‘Account Summary’ API call to find the correct names.
owner_admins_ids	array	N, L	Array of admin IDs to whom the record belongs
physical_code	number	N	Physical postal code
physical_line_1	string	N	Physical address line 1
physical_line_2	string	N	Physical address line 2
physical_line_3	string	N	Physical address line 3
physical_line_4	string	N	Physical address line 4
postal_code	string	N	Postal code
postal_line_1	string	N	Postal address line 1
postal_line_2	string	N	Postal address line 2
postal_line_3	string	N	Postal address line 3
postal_line_4	string	N	Postal address line 4
product_amount	Number	N	Amount company is paying for the product in Cents e.g. 150 for R1.50
product_name	string	N, L	Name of the product company is subscribed to. See description above for when to use product inputs.
product_subscription_start_date	date	N	When the subscription to the product is to start. If the product interval is greater than 1 month e.g. yearly, you may not pick a date that was already submitted in a batch. A good rule is that the starting date should be at least 12 days from now.
product_unit_name	string	N, L	How frequently the product is billed
project	string	N, L	Project account was recruited under
reference_number	string	N	Custom reference number to tag the product with and display on workflow reporting.
region	string	N, L	Province/State the company is located in. Defaults to none/unknown
registration_number	string	N	Registration number
social_blog	string	N	Blog URL
social_facebook	string	N	Facebook URL
social_instagram	string	N	Instagram URL
social_linkedin	string	N	LinkedIn URL
social_pinterest	string	N	Pinterest URL
social_telegram	string	N	Telegram number
social_twitter	string	N	Twitter URL
social_whatsapp	string	N	WhatsApp number
tax_reference	string	N	Company tax reference
trading_as	string	N	Registered trading name
utm_campaign	string	N	UTM campaign parameter
utm_content	string	N	UTM content parameter
utm_medium	string	N	UTM medium parameter
utm_source	string	N	UTM source parameter
utm_term	string	N	UTM term parameter
web_referrer	string	N	Web referrer URL
website	string	N	Website address
visible_to_lookups_id	string	N, L	Visibility group associated with the record

Response (JSON)

Data is returned as a JSON object in the following format with multiple sections:

{
  "Info": {
    "companies": {
      "updated": 12,
      "rejected": 3
    }
  },
  "accepted": [{...}],
  "rejected": [{
  "reasons": {  
    "account_number": {
      "message": "CDV check failed",
      "rule": "CDV"
    }
  },
  "name": "xxxxxxxxxxxx",
  ...
  }, ...]
}

Info section
Sub-section	Field name	Data type	Description
companies	updated	number	Number of records updated
companies	rejected	number	Number of records rejected (See rejected section for more details)

Rejected section

Field name

Data type

Description

reasons

object

The reason why the record was rejected; some examples include:

Person already exists
Branch code format incorrect
Account number format incorrect
Account name format incorrect
CDV check failed

The reasons are given per input key that failed the validation e.g. "account_number".

name

string

Name associated with the rejected record (company name)

Accepted section
Field name	Data type	Description
unique_workflow_id	string	Unique ID associated with the submission. Can be used to cancel the item if it is still pending.
name	string	Name associated with the rejected record (company name)

Add Product

Add a product to the subscription (or the latest active subscription) for a specified company. Subscription product agents will be based on the agent that is associated with the API token used. Body input must be an object and not an array.

Path
`/workflow/company/product/add`

Request (POST)

Field name	Data type	Required	Description
product_name	string	Y, L	Name of the product to be added for the person.
company_name	string	Y	Name of the company paying for the product. Must be unique and exist in the DB. Name is case insensitive but additional characters would affect the result. ‘MY COMPANY’ is the same as ‘My Company’ but ‘My Company LTD’ would not be found for example. Use the ‘Account Summary’ API call to find the correct names.
account_id_number	string	N	Used when paying for a specific person. ID number of the person the product is for.
subscription_id	string	N	ID of the subscription to add the product to. Obtained from ‘Account Summary’. Defaults to the latest active subscription of the company; with active banking details.
amount	Number	Y	Amount to be paid for the product; in cents.
branch	string	N, L	Branch product was recruited at
project	string	N, L	Project product was recruited under
agent	string	N, L	Agent selling the product
reference_number	string	N	Custom reference number to tag the product with and display on workflow reporting.

Response (JSON)

Data is returned as a JSON object in the following format:

{
  "billing_day": 1,
  "amount": 20000,
  "payer_name": "xxxxxxxxxxxxx",
  "account_id_number": "xxxxxxxxxxxxx",
  "product_name": "Product 123",
  "unique_workflow_id": "xxxxxxxxx",
  "errors": [{
    "message": "abc",
    "rule": "uuid"
  }]
}

Field name	Data type	Description
billing_day	Number	Day on which the next payment will be made
amount	Number	Amount in cents to be deducted from the person
payer_name	String	Name of the company paying for the product
account_id_number	String	ID number of the person receiving the product (if applicable).
product_name	String	Name of the product being paid for
unique_workflow_id	String	Unique ID associated with this workflow submission. Can be used to cancel a pending workflow item.
Errors Section
message	String	Reason why the submission was rejected: Company name does not exist Account ID number does not exist Product not found No active subscription found for the payer Bank details of the payer is not valid Subscription ID not found Branch not found Project not found The subscription id value is malformed The branch value is malformed The project value is malformed etc.
rule	String	Rule associated with the message e.g. ‘uuid’

Add Subscription

Add a new subscription for the specified company. Subscription product agents will be based on the agent that is associated with the API token used. Body input must be an object.

Path
`/workflow/company/subscription/add`

Request (POST)

Field name	Data type	Required	Description
product_name	string	Y, L	Name of the product to be added for the person.
company_name	string	Y	Name of the company paying for the product. Must be unique and exist in the DB. Name is case insensitive but additional characters would affect the result. ‘MY COMPANY’ is the same as ‘My Company’ but ‘My Company LTD’ would not be found for example. Use the ‘Account Summary’ API call to find the correct names.
account_id_number	string	N	Used when paying for someone else e.g. a spouse. ID number of the person the product is for; defaults to the person specified with ‘id_number’.
amount	number	Y	Amount to be paid for the product; in cents.
agent	string	N, L	Name of the related agent, if not same as that specified by the API token
branch	string	N, L	Branch product was recruited at
project	string	N, L	Project product was recruited under
start_date	date	N	Date when subscription is to start, defaults to next billing day
end_date	date	N	Date when subscription is to end, leave empty for no end date
billing_day	number	Y	Calendar day to make deductions on, 1 to 31
default_payment_methods_id	string	Y, L	Payment method to be used with the subscription See ‘/api/1.0/lookups?category=Payment Methods’
bank_account_name	string	C	Bank account holder name. Required when the payment method used is a debit order.
bank_account_number	string	C	Bank account number. Required when the payment method used is a debit order.
bank_account_bank	string	C, L	Name of the bank that the bank account number belongs to e.g. "ABSA’. See ‘/api/1.0/lookups/bank/names’. Required when the payment method used is a debit order.
bank_account_type_lookups_id	string	C, L	Type of bank account used e.g. ‘Cheque/Current". See ‘/api/1.0/lookups/bank/accounts’. Required when the payment method used is a debit order.
bank_account_branch_code	string	C	Branch code associated with the bank account number. Required when the payment method used is a debit order.

Response (JSON)

Data is returned as a JSON object in the following format:

{  
  "status": true,
  "errors": null,
  "billing_day": 1,
  "amount": 20000,
  ...
}

Field name	Data type	Description
status	boolean	True if the call succeeded, false if there is an error
errors	object	Object specifying the problem with inputs e.g.

{
  "product_name" {
    "message": "Product not found",
    "rule": "Lookup"
  }
}

Field name	Data type	Description
billing_day	number	Date of month payment is to be deducted on, 1 to 31
amount	number	Amount to be paid for the product; in cents.
subscription_start_date	date	When the subscription will start running, the first payment will be on the first billing day after this date and then repeat every interval from that date (based on the product interval)
subscription_end_date	date	When the subscription is to stop running
account_id_number	string	ID Number of the person being paid for
product_name	string	Name of the product being paid for
unique_workflow_id	string	Unique ID associated with this workflow submission. Can be used to cancel a pending workflow item.
payer_name	string	Name of the company paying for the product

Blacklist

Get a list of blacklisted phone numbers where the user requested not to be contacted.

Path
`/companies/blacklist/{sms\|phone}`

Request (POST)

Field name	Data type	Required	Description
start	date	N	Start date filter on when record was flagged not to contact
end	date	N	End date filter on when record was flagged not to contact

Response (JSON)

Data is returned as a JSON object in the following format:

{
  "status": true,
  "data": [{
    "cellphone": "081234567",
    "contact": "081234567",
  }]
  "error": "String message"
}

| |

Field name	Data type	Description
cellphone	String	Contact number
contact	String	Contact number
Errors Section
message	String	Reason why the API call failed: Incorrect type passed The start date is not in the correct format The end date is not in the correct format
rule	Type	Type in URL needs to be either "sms" or "phone"
rule	Date	Start and end date needs to be in format YYYY-MM-DD or 2021-01-01

Required if day_salary is not provided. ↑
Either none or all of the account related information must be provided. ↑
Either none or all of the account related information must be provided. ↑
See note 1 ↑
See note 1 ↑
See note 1 ↑
Either none or all of the product related information must be provided. ↑
See note 6 ↑
See note 6 ↑
If provided requires all account and product related information to be provided. ↑
Required if default_day_salary is not provided. In which case it is used as the profile default debit order day as well as the product debit order day. ↑
Either none or all of the account related information must be provided. ↑
See note 12 ↑
See note 12 ↑
See note 12 ↑
See note 12 ↑
Either none or all of the product related information must be provided. ↑
See note 17 ↑
See note 17 ↑
If provided requires all account and product related information to be provided. ↑
Required if default_day_salary is not provided. In which case it is used as the company default debit order day as well as the product debit order day. ↑
Required if day_salary is not provided. ↑

People

Contact Centre People API documentation

Calls

Contact Centre Calls API documentation

Account Summary

Record section

Subscription section

Bank accounts section

Transactions section

Add New Company

Info section

Rejected section

Accepted section

Update Company

Info section

Rejected section

Accepted section

Add Product

Add Subscription

Blacklist