Saint Peter Opt-Out System - API Documentation

Base URL: https://saintpeter-yonder.scstage.scprod.yonder.cloud

Authentication

All API endpoints require Bearer Token Authentication via Laravel Sanctum.

Authentication Header

Include this header in every API request:

Authorization: Bearer YOUR_TOKEN_HERE

To obtain your token: Contact the support team at support@yonder.co.za

Common URL Parameters

These parameters are used across multiple endpoints and will be provided to each publisher/provider:

Parameter	Description	Example
providerSlug	Your unique provider identifier	`yonder`, `egentic`
clientSlug	Your unique client identifier	`legalwise`, `client1`
msisdn	Phone number in SA format (11 digits)	`27123456789`
opt_out_date	Date in YYYY-MM-DD format (optional)	`2023-07-01`

Note: Provider and client identifiers will be supplied to you during onboarding.

Phone Number Format

All phone numbers must be in South African format:

Format: 27XXXXXXXXX (11 digits starting with 27)
Valid Example: 27123456789
Invalid Examples: 0123456789, +27123456789, 123456789

The system will attempt to normalize numbers, but submitting in the correct format is recommended.

Date Format

Opt-out dates should be provided in one of these formats:

Preferred: YYYY-MM-DD (e.g., 2023-07-01)
Also Accepted: YYYY/MM/DD, DD/MM/YYYY

If no date is provided or the format is invalid, the current date will be used automatically.

API Endpoints

1. Bulk Interrogation

Check if multiple phone numbers are already opted-out.

Use Case: Before sending a campaign to thousands of numbers, filter out opted-out numbers.

Property	Value
Method	`GET`
Endpoint	`/api/interrogate/bulk/providerSlug/clientSlug`
Content-Type	`application/json`

Request

curl -X GET "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/interrogate/bulk/providerSlug/clientSlug" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "numbers": ["27123456789", "27987654321", "27111111111"]
}'

Input Payload

{
  "numbers": ["27123456789", "27987654321", "27111111111"]
}

Output Response

[
  {
    "number": "27123456789",
    "status": "opted-out",
    "opt_out_date": "2023-06-15"
  },
  {
    "number": "27987654321",
    "status": "not-found"
  },
  {
    "number": "27111111111",
    "status": "invalid",
    "message": "Invalid cellphone number"
  }
]

Response Fields

Field	Type	Description
`number`	string	The phone number that was checked
`status`	string	`opted-out`, `not-found`, or `invalid`
`opt_out_date`	string	Date when opted out (only if status is `opted-out`)
`message`	string	Error message (only if status is `invalid`)

2. Bulk Opt-Out

Add multiple phone numbers to the opt-out list at once.

Use Case: Submit a batch of opt-out requests in one API call.

Property	Value
Method	`POST`
Endpoint	`/api/optout/bulk/providerSlug/clientSlug`
Content-Type	`application/json`

Request

curl -X POST "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/optout/bulk/providerSlug/clientSlug" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "numbers": [
    {"cell_number": "27123456789", "opt_out_date": "2023-07-01"},
    {"cell_number": "27987654321", "opt_out_date": "2023-07-02"},
    {"cell_number": "27111111111"}
  ]
}'

Input Payload

{
  "numbers": [
    {
      "cell_number": "27123456789",
      "opt_out_date": "2023-07-01"
    },
    {
      "cell_number": "27987654321",
      "opt_out_date": "2023-07-02"
    },
    {
      "cell_number": "27111111111"
    }
  ]
}

Note: opt_out_date is optional. If not provided, the current date will be used.

Output Response

[
  {
    "number": "27123456789",
    "status": "opted-out successfully",
    "opt_out_date": "2023-07-01"
  },
  {
    "number": "27987654321",
    "status": "exists",
    "opt_out_date": "2023-06-15"
  },
  {
    "number": "27111111111",
    "status": "opted-out successfully",
    "opt_out_date": "Opt-out date was not provided or invalid and therefore has been set to: 2024-04-20"
  }
]

Response Fields

Field	Type	Description
`number`	string	The phone number that was processed
`status`	string	`opted-out successfully`, `exists`, or `invalid`
`opt_out_date`	string	The opt-out date (provided or auto-generated)

3. Single Interrogation

Check if one specific phone number is opted-out.

Use Case: Real-time check before sending a single SMS.

Property	Value
Method	`GET`
Endpoint	`/api/interrogate/providerSlug/clientSlug/msisdn`

Request

curl -X GET "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/interrogate/providerSlug/clientSlug/msisdn" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example with actual values:

curl -X GET "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/interrogate/yonder/legalwise/27123456789" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Input Payload

None - all parameters are in the URL.

Output Response (Found)

{
  "number": "27123456789",
  "status": "opted-out",
  "opt_out_date": "2023-06-15"
}

Output Response (Not Found)

{
  "number": "27123456789",
  "status": "not-found"
}

Output Response (Invalid)

{
  "number": "123",
  "status": "invalid"
}

4. Single Opt-Out

Add one phone number to the opt-out list.

Use Case: When a customer replies "STOP" to an SMS, immediately opt them out.

Property	Value
Method	`POST`
Endpoint	`/api/optout/providerSlug/clientSlug/msisdn/opt_out_date` (with date) `/api/optout/providerSlug/clientSlug/msisdn` (without date)

Request (with date)

curl -X POST "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/optout/providerSlug/clientSlug/msisdn/opt_out_date" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example with actual values:

curl -X POST "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/optout/yonder/legalwise/27123456789/2023-07-01" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Request (without date - uses current date)

curl -X POST "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/optout/providerSlug/clientSlug/msisdn" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Input Payload

None - all parameters are in the URL.

Output Response (Success)

{
  "number": "27123456789",
  "status": "opted-out successfully"
}

Output Response (Already Exists)

{
  "number": "27123456789",
  "opt_out_date": "2023-06-15",
  "status": "exists"
}

Output Response (Invalid)

{
  "number": "123",
  "status": "invalid"
}

5. MSISDN Interrogation

Check opt-out status across all clients for a specific provider.

Use Case: Provider-level check without needing to specify which client.

Property	Value
Method	`GET`
Endpoint	`/api/interrogateMsisdn/msisdn/providerSlug`

Request

curl -X GET "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/interrogateMsisdn/msisdn/providerSlug" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example with actual values:

curl -X GET "https://saintpeter-yonder.scstage.scprod.yonder.cloud/api/interrogateMsisdn/27123456789/yonder" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Input Payload

None - all parameters are in the URL.

Output Response (Found)

{
  "number": "27123456789",
  "status": "opted-out",
  "opt_out_date": "2023-06-15"
}

Output Response (Not Found)

{
  "number": "27123456789",
  "status": "not-found"
}

Common Error Responses

Invalid Client or Provider

{
  "error": "Invalid client or provider"
}

Cause: The providerSlug or clientSlug provided doesn't exist or you don't have access to it.

No Numbers Provided (Bulk endpoints only)

{
  "error": "No numbers provided"
}

Cause: The numbers array is empty or missing.

No Valid Numbers Provided (Bulk endpoints only)

{
  "error": "No valid numbers provided"
}

Cause: All numbers in the request are invalid.

Unauthorized (401)

HTTP Status Code: 401

Cause: Missing or invalid Bearer token.

Integration Methods Comparison

Method	Use Case	Processing Time	Best For
API (Real-time)	Immediate verification/submission	Instant	Live systems, real-time checks
SFTP (Batch)	Large file uploads	Every 15 minutes	Bulk processing, scheduled updates
Web Upload	Manual uploads	Immediate	Small datasets, occasional use

Quick Reference

Endpoint Summary

Endpoint	Method	Purpose
`/api/interrogate/bulk/providerSlug/clientSlug`	GET	Check multiple numbers
`/api/optout/bulk/providerSlug/clientSlug`	POST	Opt-out multiple numbers
`/api/interrogate/providerSlug/clientSlug/msisdn`	GET	Check single number
`/api/optout/providerSlug/clientSlug/msisdn/opt_out_date`	POST	Opt-out single number
`/api/interrogateMsisdn/msisdn/providerSlug`	GET	Check number (provider-level)

Required Headers

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json  (for POST/GET with body)

Support

For technical support, API token requests, or questions:

Email: support@yonder.co.za

Changelog

Version 2.0 - Restructured documentation

Common elements moved to top
Clearer endpoint layout with input/output sections
Added actual value examples
Improved quick reference section

Version 1.0 - Initial API documentation