People

Account Summary

All members are stored on the platform as an account. This API call will return summary data

Path
`/workflow/people/details`

Request (POST)

Any of the following fields can be sent

Field name	Data type	Description
id_number	string	ID number, this can also be other countries
member_number	string	Membership 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": {
    "member_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
name	string	First name
surname	string	Last name
email	string	Email
id_number	string	Local or foreign ID number
id_number_type	String	Type of ID number e.g. ‘SA ID Number’ or ‘Passport’
contact_cell	string	Contact number (10 digits)
contact_home	string	Home number (10 digits)
contact_work	string	Work number (10 digits)
contact_fax	string	Fax number (10 digits)
tax_reference	string	Tax reference number
country	string	Country the person resides in
region	string	province/state associated with above country
municipality	String	Municipality associated with the region
title	string	Title
language	string	Language
marital_status	string	Marital Status
branch	string	Branch account was recruited at
agent	string	Agent who recruited account
day_salary	number	Day of debit order run (0 - 31)
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
created_at	timestamp	When record was created
updated_at	timestamp	When record was updated
balance_open	number	Journal opening balance
date_balance_open	date	Date associated with opening balance
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
companies_name	string	Name of the company associated with the person
companies_trading_as	string	Trading name of the company associated with the person
is_blacklisted	boolean	Has this person been flagged as blacklisted
middle_names	string	Middle name(s) of the person
job_title	string	Job the person does
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 person by call
call_last_contacted	date	Date when last the person was contacted via call
date_phone_invalid	date	Date when the phone number was deemed invalid
date_lead_conversion	date	Date when the person was converted from a lead to an account
date_paid_up	date	Date until when the person is deemed to be paid up
address_details_changed_at	date	Date when the address details of the person was changed
contact_details_changed_at	date	Date when the contact details of the person was changed
last_engagement_at	date	Date when the person was last engaged with
status_changed_at	date	Date when the status of the person was last changed at
source_of_record_title	string	Source of the record e.g. API
date_id_number_verify	date	Date when the ID number was verified
credit_score_cpa	number	CPA credit score of the person
credit_score_nlr	number	NLR credit score of the person
referred_by	string	Who this person 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 where 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 Person

This API call will provide for loading new members onto the platform.

Path
`/workflow/people/create`

Request (POST) JSON Array

Field name	Data type	Required	Description
account_bank	string	C^{^[6]}, L	Bank name
account_branch_code	string	C^{^[2]}, L	Bank branch code
account_name	string	C^{^[3]}	Bank account holder name
account_number	string	C^{^[4]}	Bank account number
account_type	string	C^{^[5]}, 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	Billing day subscription is to run on (used when adding a product)
branch	string	N, L	Branch account was recruited at
companies_id	string	N	ID of the company associated with this person
contact_cell	string	Y	Contact number (10 digits)
contact_fax	string	N	Fax number (10 digits)
contact_home	string	N	Home number (10 digits)
contact_work	string	N	Work number (10 digits)
country	string	N, L	Country the person lives 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 associated with opening balance
date_birth	date	N	Date of birth
day_salary	number	C^{^[11]}	Day of debit order run for product (0 - 31). Only applicable if product details above have been provided.
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_billing_day	number	N	Default billing day for the person
default_day_salary	string	C^{^[1]}	Default debit order day for the person
email	string	N	Email
gender	string	Y, L	Person gender
id_number_type	string	N, L	Defaults to ‘SA ID Number’
id_number	string	Y	ID number, this can also be other countries
initials	string	N	Person initials
is_active	boolean	N	Person record is to be active. Defaults to true.
is_blacklisted	boolean	N	If this person 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
job_lookups_id	string	N, L	The type of job the person does
language	string	Y, L	Language
middle_names	string	N	Middle names of the person
marital_status	string	N, L	Marital status
municipality	String	N, L	Municipality associated with the region
name	string	Y	First name
owner_admins_ids	array	N, L	Array of admin IDs to whom the record belongs
physical_code	number	Y	Physical postal code
physical_line_1	string	Y	Physical address line 1
physical_line_2	string	Y	Physical address line 2
physical_line_3	string	Y	Physical address line 3
physical_line_4	string	Y	Physical address line 4
postal_code	string	Y	Postal code
postal_line_1	string	Y	Postal address line 1
postal_line_2	string	Y	Postal address line 2
postal_line_3	string	Y	Postal address line 3
postal_line_4	string	Y	Postal address line 4
product_amount	Number	C^{^[8]}	Amount person is paying for the product in Cents e.g. 150 for R1.50
product_name	string	C^{^[7]}, L	Name of the product person is subscribed to
product_subscription_start_date	date	C^{^[10]}	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^{^[9]}, 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 person lives in. Defaults to none/unknown
surname	string	Y	Last name
tax_reference	string	N	Tax reference number associated with the person
title	string	N, L	Title
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": {
    "people": {
      "accepted": 12345,
      "rejected": 678
    }
  },
  "accepted": [{...}],
  "rejected": [{
    "reasons": {
      "account_number": {
        "message": "CDV check failed", "rule": "CDV"
      }
    },
    "id_number": "xxxxxxxxxxxx",
    ...
  }, ...]
}

Info section
Sub-section	Field name	Data type	Description
people	accepted	number	Number of records accepted
people	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".
id_number	string	ID number associated with the rejected record
name	string	First name
surname	string	Last 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.
id_number	string	ID number associated with the rejected record
name	string	First name
surname	string	Last name

Update Person

This API call will provide for updating the details of existing members 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 person 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 people that currently have no active subscriptions. To add products to an existing subscription use the ‘add product’ API call.

Path
`/workflow/people/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	Billing day subscription is to run on (used when adding a product)
branch	string	N, L	Branch account was recruited at
companies_id	string	N	ID of the company associated with this person
contact_cell	string	N	Contact number (10 digits)
contact_fax	string	N	Fax number (10 digits)
contact_home	string	N	Home number (10 digits)
contact_work	string	N	Work number (10 digits)
country	string	N, L	Country the person lives 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 associated with opening balance
date_birth	date	N	Date of birth
day_salary	number	N	Day of debit order run for the product (0 - 31). Only applicable to product details above.
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_billing_day	number	N	Default billing day for the person
default_day_salary	string	N	Default debit order day for the person
email	string	N	Email
gender	string	N, L	Person gender
id_number_type	string	N, L	Defaults to ‘SA ID Number’
id_number	string	Y	ID number of the person to be updated
initials	string	N	Person initials
is_active	boolean	N	Person record is to be active. Defaults to true.
is_blacklisted	boolean	N	If this person 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
job_lookups_id	string	N, L	The type of job the person does
language	string	N, L	Language
marital_status	string	N, L	Marital status
middle_names	string	N	Middle names of the person
municipality	String	N, L	Municipality associated with the region
name	string	N	First name
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	string	N	Amount person is paying for the product in Cents e.g. 150 for R1.50
product_name	string	N, L	Name of the product person is subscribed to. See description above for when to use the product related 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 person lives in. Defaults to none/unknown
surname	string	N	Last name
tax_reference	string	N	Tax reference number associated with the person
title	string	N, L	Title
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": {
    "people": {
      "updated": 12,
      "rejected": 3
    }
  },
  "accepted": [{...}],
  "rejected": [{
    "reasons": {  
      "account_number": {
        "message": "CDV check failed", "rule": "CDV"
      }
    },
    "id_number": "xxxxxxxxxxxx",
    ...
  }, ...]
}

Info section
Sub-section	Field name	Data type	Description
people	updated	number	Number of records updated
people	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".
id_number	string	ID number associated with the rejected record
name	string	First name
surname	string	Last 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.
id_number	string	ID number associated with the rejected record
name	string	First name
surname	string	Last name

Add Product

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

Path
`/workflow/people/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.
id_number	string	Y	ID number of the person paying for the product.
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’.
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 person; 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
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_id_number": "xxxxxxxxxxxxx",
  "account_id_number": "xxxxxxxxxxxxx",
  "product_name": "Product 123",
  "unique_workflow_id" "xxxxxxxxxx",
  "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_id_number	String	ID number of the person paying for the product
account_id_number	String	ID number of the person receiving the product
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: Payer ID number 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 person. 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/people/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.
id_number	string	Y	ID number of the person paying for the product.
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_id_number	string	ID Number of the person paying for the product

Blacklist

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

Path
`/people/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",
    "work": "081234567",
    "home": "081234567",
  }],
  "error": "String message"
}

Field name	Data type	Description
cellphone	String	Contact number
work	String	Contact number
home	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

General

Contact Centre General API Calls

Companies

Contact Centre Companies API documentation

Account Summary

Record section

Subscription section

Bank accounts section

Transactions section

Add New Person

Info section

Rejected section

Accepted section

Update Person

Info section

Rejected section

Accepted section

Add Product

Add Subscription

Blacklist