This is the API Documentation for Somleng Simple Call Flow Manager (Somleng SCFM).
Access Tokens
Create an Access Token
Request
curl "https://scfm.somleng.org/api/access_tokens" -d '{
"metadata": {
"foo": "bar"
},
"permissions": [
"contacts_write"
]
}' -X POST \
-H "Authorization: Bearer 2qIM9teSJBRFuQTFL_ADAJiWtbrkB7--Ms4IvtIbTjE"
Endpoint
POST /api/access_tokens
POST /api/access_tokens
Parameters
{
"metadata": {
"foo": "bar"
},
"permissions": [
"contacts_write"
]
}
Name | Description |
---|---|
permissions | An array of permissions for the access token. Valid permissions are: access_tokens_read , access_tokens_write , accounts_read , accounts_write , batch_operations_read , batch_operations_write , callout_participations_read , callout_participations_write , callouts_read , callouts_write , contacts_read , contacts_write , phone_calls_read , phone_calls_write , remote_phone_call_events_read , remote_phone_call_events_write , users_read , users_write , recordings_read |
Response
location: /api/access_tokens/16
201 Created
{
"id": 16,
"token": "vL9yW-1mxMsaWRZPnh7okmVggV0DOTaFSe3RKCrTVI8",
"created_at": "2024-04-05T07:32:22.420Z",
"updated_at": "2024-04-05T07:32:22.422Z",
"metadata": {
"foo": "bar"
},
"permissions": [
"contacts_write"
]
}
Delete an Access Token
Request
curl "https://scfm.somleng.org/api/access_tokens/21" -d '' -X DELETE \
-H "Authorization: Bearer cCGM8L4fzrm0vkxZiyziermzGUafqNgVtuTb2JJNh6g"
Endpoint
DELETE /api/access_tokens/:id
DELETE /api/access_tokens/21
Parameters
None known.
Response
location: /api/access_tokens
204 No Content
List all Access Tokens
Request
curl -g "https://scfm.somleng.org/api/access_tokens?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer zDpPxI3xFQWjnv0sTK0c4OBqiswW6L3JJiKqGQH3oo0"
Endpoint
GET /api/access_tokens
GET /api/access_tokens?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
Name | Description |
---|---|
q | A filter in which to filter resources |
Response
per-page: 25
total: 1
200 OK
[
{
"id": 11,
"token": "UPnAEioDyXerl1MSTyrVLcWqHwSsWezeQVbh2jqOAGs",
"created_at": "2024-04-05T07:32:22.370Z",
"updated_at": "2024-04-05T07:32:22.371Z",
"metadata": {
"foo": "bar"
},
"permissions": [
]
}
]
Retrieve an Access Token
Request
curl -g "https://scfm.somleng.org/api/access_tokens/19" -X GET \
-H "Authorization: Bearer 93jhmHuZcRQ1VrbjjH20uCkxAamd3cTjwH7AIB8e9xI"
Endpoint
GET /api/access_tokens/:id
GET /api/access_tokens/19
Parameters
None known.
Response
location: /api/access_tokens/19
200 OK
{
"id": 19,
"token": "93jhmHuZcRQ1VrbjjH20uCkxAamd3cTjwH7AIB8e9xI",
"created_at": "2024-04-05T07:32:22.451Z",
"updated_at": "2024-04-05T07:32:22.453Z",
"metadata": {
},
"permissions": [
"access_tokens_read",
"access_tokens_write"
]
}
Update an Access Token
Request
curl "https://scfm.somleng.orgapi/access_tokens/20" -d '{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer Bi_DjgiXj-Rg3CV3soamt8Jha3rTIObd5KA9Q7KsU2M"
Endpoint
PATCH api/access_tokens/:id
PATCH api/access_tokens/20
Parameters
{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/access_tokens/20
204 No Content
Account Details
Retrieve Account Details
Request
curl -g "https://scfm.somleng.org/api/account" -X GET \
-H "Authorization: Bearer qX1DsX23HF8jh76YuJbQuDpbVnm6r9hqs0T811K9ans"
Endpoint
GET /api/account
GET /api/account
Parameters
None known.
Response
location: /api/accounts/398
200 OK
{
"id": 398,
"metadata": {
},
"settings": {
"from_phone_number": "1234",
"phone_call_queue_limit": 200,
"max_phone_calls_for_callout_participation": 3
},
"twilio_account_sid": null,
"somleng_account_sid": null,
"twilio_auth_token": null,
"somleng_auth_token": null,
"permissions": [
],
"created_at": "2024-04-05T07:32:22.511Z",
"updated_at": "2024-04-05T07:32:22.511Z",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": null,
"somleng_api_host": null,
"somleng_api_base_url": null,
"phone_calls_count": 0,
"contacts_count": 0
}
Update Account Details
Request
curl "https://scfm.somleng.org/api/account" -d '{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer PXkhSigu8VmKOt2XvqvtGW82xFZjJeoO0EHKQrlTvLI"
Endpoint
PATCH /api/account
PATCH /api/account
Parameters
{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/accounts/399
204 No Content
Accounts
Only super admins can manage accounts.
Create an Account
Request
curl "https://scfm.somleng.org/api/accounts" -d '' -X POST \
-H "Authorization: Bearer A2jOR2XC1-QYBR-5WNAG_i5j3yOQoVhD2BSzsGEbFZ4"
Endpoint
POST /api/accounts
POST /api/accounts
Parameters
None known.
Response
location: /api/accounts/404
201 Created
{
"id": 404,
"metadata": {
},
"settings": {
"from_phone_number": "1234",
"phone_call_queue_limit": 200,
"max_phone_calls_for_callout_participation": 3
},
"twilio_account_sid": null,
"somleng_account_sid": null,
"twilio_auth_token": null,
"somleng_auth_token": null,
"permissions": [
],
"created_at": "2024-04-05T07:32:22.573Z",
"updated_at": "2024-04-05T07:32:22.573Z",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": null,
"somleng_api_host": null,
"somleng_api_base_url": null,
"phone_calls_count": 0,
"contacts_count": 0
}
Delete an Account
Request
curl "https://scfm.somleng.org/api/accounts/409" -d '' -X DELETE \
-H "Authorization: Bearer MhS1H6xHYJXVjWokL7ilm20S2jvHtXAz_5Qvvd9CB-s"
Endpoint
DELETE /api/accounts/:id
DELETE /api/accounts/409
Parameters
None known.
Response
location: /api/accounts
204 No Content
List all Accounts
Request
curl -g "https://scfm.somleng.org/api/accounts?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer Y4OfU0-qL_GT_syRUOtUdET00SxqEUp9Jzo7CCJ6sGE"
Endpoint
GET /api/accounts
GET /api/accounts?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 400,
"metadata": {
"foo": "bar"
},
"settings": {
"from_phone_number": "1234",
"phone_call_queue_limit": 200,
"max_phone_calls_for_callout_participation": 3
},
"twilio_account_sid": null,
"somleng_account_sid": null,
"twilio_auth_token": null,
"somleng_auth_token": null,
"permissions": [
],
"created_at": "2024-04-05T07:32:22.533Z",
"updated_at": "2024-04-05T07:32:22.533Z",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": null,
"somleng_api_host": null,
"somleng_api_base_url": null,
"phone_calls_count": 0,
"contacts_count": 0
}
]
Retrieve an Account
Request
curl -g "https://scfm.somleng.org/api/accounts/405" -X GET \
-H "Authorization: Bearer z4AT4TveSzAuVstdKfDIJJBf6Amd5XNRblok074o_yA"
Endpoint
GET /api/accounts/:id
GET /api/accounts/405
Parameters
None known.
Response
location: /api/accounts/405
200 OK
{
"id": 405,
"metadata": {
},
"settings": {
"from_phone_number": "1234",
"phone_call_queue_limit": 200,
"max_phone_calls_for_callout_participation": 3
},
"twilio_account_sid": null,
"somleng_account_sid": null,
"twilio_auth_token": null,
"somleng_auth_token": null,
"permissions": [
],
"created_at": "2024-04-05T07:32:22.578Z",
"updated_at": "2024-04-05T07:32:22.578Z",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": null,
"somleng_api_host": null,
"somleng_api_base_url": null,
"phone_calls_count": 0,
"contacts_count": 0
}
Update an Account
Request
curl "https://scfm.somleng.org/api/accounts/407" -d '{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace",
"twilio_account_sid": "AC8",
"somleng_account_sid": "d5a14f57-7b65-415b-9f89-c46be0f31767",
"twilio_auth_token": "37a90cb6-668b-4f48-8e4d-e5ad1886cfed",
"somleng_auth_token": "10f3f9d8-635a-427d-8040-531cdfa6109f",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": "somleng",
"settings": {
"batch_operation_phone_call_create_parameters": {
"callout_filter_params": {
"status": "running"
},
"callout_participation_filter_params": {
"no_phone_calls_or_last_attempt": "failed"
},
"remote_request_params": {
"from": "1234",
"url": "https://demo.twilio.com/docs/voice.xml",
"method": "GET"
}
},
"batch_operation_phone_call_queue_parameters": {
"callout_filter_params": {
"status": "running"
},
"phone_call_filter_params": {
"status": "created"
},
"limit": "30"
},
"batch_operation_phone_call_queue_remote_fetch_parameters": {
"phone_call_filter_params": {
"status": "remotely_queued,in_progress"
},
"limit": "30"
}
}
}' -X PATCH \
-H "Authorization: Bearer bU5zmCj0cZDDGYPIB8eNx2-02q5TAxbdxPUcGR-q_GY"
Endpoint
PATCH /api/accounts/:id
PATCH /api/accounts/407
Parameters
{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace",
"twilio_account_sid": "AC8",
"somleng_account_sid": "d5a14f57-7b65-415b-9f89-c46be0f31767",
"twilio_auth_token": "37a90cb6-668b-4f48-8e4d-e5ad1886cfed",
"somleng_auth_token": "10f3f9d8-635a-427d-8040-531cdfa6109f",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"platform_provider_name": "somleng",
"settings": {
"batch_operation_phone_call_create_parameters": {
"callout_filter_params": {
"status": "running"
},
"callout_participation_filter_params": {
"no_phone_calls_or_last_attempt": "failed"
},
"remote_request_params": {
"from": "1234",
"url": "https://demo.twilio.com/docs/voice.xml",
"method": "GET"
}
},
"batch_operation_phone_call_queue_parameters": {
"callout_filter_params": {
"status": "running"
},
"phone_call_filter_params": {
"status": "created"
},
"limit": "30"
},
"batch_operation_phone_call_queue_remote_fetch_parameters": {
"phone_call_filter_params": {
"status": "remotely_queued,in_progress"
},
"limit": "30"
}
}
}
None known.
Response
location: /api/accounts/407
204 No Content
Batch Operations
Create a Batch Operation Event
Request
curl "https://scfm.somleng.org/api/batch_operations/28/batch_operation_events" -d '{
"event": "queue"
}' -X POST \
-H "Authorization: Bearer mOm-w-ytyAPhppUWxDCUnmxIycvI-4nspR2vqlVQk_A"
Endpoint
POST /api/batch_operations/:batch_operation_id/batch_operation_events
POST /api/batch_operations/28/batch_operation_events
Parameters
{
"event": "queue"
}
Name | Description |
---|---|
event required | Either queue . |
Response
location: /api/batch_operations/28
201 Created
{
"id": 28,
"callout_id": 192,
"parameters": {
},
"metadata": {
},
"status": "queued",
"created_at": "2024-04-05T07:32:22.824Z",
"updated_at": "2024-04-05T07:32:22.824Z",
"account_id": 424,
"type": "BatchOperation::CalloutPopulation"
}
Delete a Batch Operation
Request
curl "https://scfm.somleng.org/api/batch_operations/26" -d '' -X DELETE \
-H "Authorization: Bearer 4pyYZOuBd6GzLE9a-99YfjV8t97phvUPQ8F2AhF1O30"
Endpoint
DELETE /api/batch_operations/:id
DELETE /api/batch_operations/26
Parameters
None known.
Response
location: /api/batch_operations
204 No Content
List all Batch Operations
Request
curl -g "https://scfm.somleng.org/api/batch_operations?q[callout_id]=182" -X GET \
-H "Authorization: Bearer oVl3jj3RlhR3aQVSSjW5ozVvseEjzduxCMyqpSHvyvE"
Endpoint
GET /api/batch_operations
GET /api/batch_operations?q[callout_id]=182
Parameters
q: {"callout_id"=>"182"}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 20,
"callout_id": 182,
"parameters": {
},
"metadata": {
},
"status": "preview",
"created_at": "2024-04-05T07:32:22.664Z",
"updated_at": "2024-04-05T07:32:22.664Z",
"account_id": 413,
"type": "BatchOperation::CalloutPopulation"
}
]
Populate a Callout
Creates a batch operation for populating a callout with callout participations.
Specify contact_filter_params
in order to filter which contacts will participate in the callout.
Request
curl "https://scfm.somleng.org/api/batch_operations" -d '{
"callout_id": 185,
"metadata": {
"foo": "bar"
},
"parameters": {
"contact_filter_params": {
"metadata": {
"gender": "f",
"date_of_birth.date.gteq": "2022-01-01",
"date_of_birth.date.lt": "2022-02-01",
"deregistered_at.exists": false
}
}
},
"type": "BatchOperation::CalloutPopulation"
}' -X POST \
-H "Authorization: Bearer hwTtMFq7X-YFFkcBipGG4ETJPT0BSvXb58zQrQTHD-Q"
Endpoint
POST /api/batch_operations
POST /api/batch_operations
Parameters
{
"callout_id": 185,
"metadata": {
"foo": "bar"
},
"parameters": {
"contact_filter_params": {
"metadata": {
"gender": "f",
"date_of_birth.date.gteq": "2022-01-01",
"date_of_birth.date.lt": "2022-02-01",
"deregistered_at.exists": false
}
}
},
"type": "BatchOperation::CalloutPopulation"
}
Name | Description |
---|---|
type required | Must be: BatchOperation::CalloutPopulation |
parameters | Parameters for the batch operation. |
contact_filter_params
filter the contacts by the specified params.
|
| callout_id | The id
of the callout. |
Response
location: /api/batch_operations/23
201 Created
{
"id": 23,
"callout_id": 185,
"parameters": {
"contact_filter_params": {
"metadata": {
"gender": "f",
"date_of_birth.date.gteq": "2022-01-01",
"date_of_birth.date.lt": "2022-02-01",
"deregistered_at.exists": false
}
}
},
"metadata": {
"foo": "bar"
},
"status": "preview",
"created_at": "2024-04-05T07:32:22.701Z",
"updated_at": "2024-04-05T07:32:22.701Z",
"account_id": 415,
"type": "BatchOperation::CalloutPopulation"
}
Retrieve a Batch Operation
Request
curl -g "https://scfm.somleng.org/api/batch_operations/24" -X GET \
-H "Authorization: Bearer kcQK-Z7OV6uyVBiiQe6G9w_SLX8gb1Vk_Sv9c6XWSNo"
Endpoint
GET /api/batch_operations/:id
GET /api/batch_operations/24
Parameters
None known.
Response
location: /api/batch_operations/24
200 OK
{
"id": 24,
"callout_id": 187,
"parameters": {
},
"metadata": {
},
"status": "preview",
"created_at": "2024-04-05T07:32:22.744Z",
"updated_at": "2024-04-05T07:32:22.744Z",
"account_id": 418,
"type": "BatchOperation::CalloutPopulation"
}
Update a Batch Operation
Request
curl "https://scfm.somleng.org/api/batch_operations/25" -d '{
"metadata": {
"foo": "bar",
"bar": "foo"
},
"parameters": {
"contact_filter_params": {
"metadata": {
"foo": "bar"
}
}
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer j44vvlRv_eOsTRujsf1Z7i9u9SnQj8g_cMWOiuzfg5s"
Endpoint
PATCH /api/batch_operations/:id
PATCH /api/batch_operations/25
Parameters
{
"metadata": {
"foo": "bar",
"bar": "foo"
},
"parameters": {
"contact_filter_params": {
"metadata": {
"foo": "bar"
}
}
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/batch_operations/25
204 No Content
Callout Participations
Create a Callout Participation
Request
curl "https://scfm.somleng.org/api/callouts/201/callout_participations" -d '{
"contact_id": 206,
"msisdn": "252662345995",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
}
}' -X POST \
-H "Authorization: Bearer 1sLG25XeeQCvfmL45mcljvIau-0AXY6smDJS2BUfJC8"
Endpoint
POST /api/callouts/:callout_id/callout_participations
POST /api/callouts/201/callout_participations
Parameters
{
"contact_id": 206,
"msisdn": "252662345995",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
}
}
None known.
Response
location: /api/callout_participations/165
201 Created
{
"id": 165,
"callout_id": 201,
"contact_id": 206,
"callout_population_id": null,
"msisdn": "+252662345995",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
},
"created_at": "2024-04-05T07:32:22.970Z",
"updated_at": "2024-04-05T07:32:22.970Z",
"answered": false,
"phone_calls_count": 0
}
Create a Callout Participation with invalid data
Request
curl "https://scfm.somleng.org/api/callouts/202/callout_participations" -d '' -X POST \
-H "Authorization: Bearer wWsxStoEcfjK71U-FcgbZScGjwVZpkBEaDs3LPqXhrE"
Endpoint
POST /api/callouts/:callout_id/callout_participations
POST /api/callouts/202/callout_participations
Parameters
None known.
Response
422 Unprocessable Entity
{
"errors": {
"msisdn": [
"can't be blank"
],
"contact": [
"must exist"
]
}
}
Delete a Callout Participation
Request
curl "https://scfm.somleng.org/api/callout_participations/168" -d '' -X DELETE \
-H "Authorization: Bearer qhgoJbKi3H-NHZLM1KRRDvUNXeHENZ-V-MbTDWU3kCw"
Endpoint
DELETE /api/callout_participations/:id
DELETE /api/callout_participations/168
Parameters
None known.
Response
location: /api/callout_participations
204 No Content
Delete a Callout Participation with phone calls
Request
curl "https://scfm.somleng.org/api/callout_participations/169" -d '' -X DELETE \
-H "Authorization: Bearer lTjZVBnAftvZaMi31P5ZcoZRYPIHGW0BdtrMFJFfY0c"
Endpoint
DELETE /api/callout_participations/:id
DELETE /api/callout_participations/169
Parameters
None known.
Response
422 Unprocessable Entity
{
"errors": {
"base": [
"Cannot delete record because dependent phone calls exist"
]
}
}
List all Callout Participations
Request
curl -g "https://scfm.somleng.org/api/callout_participations?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer ZPMrub9t_XppwH1XR7filT3NZyR6gegqVa3n3gQS1sk"
Endpoint
GET /api/callout_participations
GET /api/callout_participations?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 158,
"callout_id": 194,
"contact_id": 199,
"callout_population_id": null,
"msisdn": "+252662345987",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
},
"created_at": "2024-04-05T07:32:22.871Z",
"updated_at": "2024-04-05T07:32:22.871Z",
"answered": false,
"phone_calls_count": 0
}
]
Retrieve a Callout Participation
Request
curl -g "https://scfm.somleng.org/api/callout_participations/166" -X GET \
-H "Authorization: Bearer g1YDSnslH7RyYha_QFN9YsG9jaWT-JnFOIrbUKbZBOc"
Endpoint
GET /api/callout_participations/:id
GET /api/callout_participations/166
Parameters
None known.
Response
location: /api/callout_participations/166
200 OK
{
"id": 166,
"callout_id": 203,
"contact_id": 207,
"callout_population_id": null,
"msisdn": "+252662345996",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
},
"created_at": "2024-04-05T07:32:22.998Z",
"updated_at": "2024-04-05T07:32:22.998Z",
"answered": false,
"phone_calls_count": 0
}
Update a Callout Participation
Request
curl "https://scfm.somleng.org/api/callout_participations/167" -d '{
"contact_id": 209,
"msisdn": "252662345999",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer J3GmIWThEvwcZeUbtll8owXdUdnShGOy-xNl3pHrI0M"
Endpoint
PATCH /api/callout_participations/:id
PATCH /api/callout_participations/167
Parameters
{
"contact_id": 209,
"msisdn": "252662345999",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/callout_participations/167
204 No Content
Callouts
Create a Callout
Request
curl "https://scfm.somleng.org/api/callouts" -d '{
"call_flow_logic": "CallFlowLogic::HelloWorld",
"audio_url": "https://www.example.com/sample.mp3",
"metadata": {
"foo": "bar"
},
"settings": {
"external_service_1": {
"foo": "bar"
}
}
}' -X POST \
-H "Authorization: Bearer HQjRygSAwhu5HMHIpuMr7iavdyi7ESP04Mj0s2wruV4"
Endpoint
POST /api/callouts
POST /api/callouts
Parameters
{
"call_flow_logic": "CallFlowLogic::HelloWorld",
"audio_url": "https://www.example.com/sample.mp3",
"metadata": {
"foo": "bar"
},
"settings": {
"external_service_1": {
"foo": "bar"
}
}
}
Name | Description |
---|---|
call_flow_logic | The name of the call flow logic to be run during the callout. |
audio_url | The URL to an audio file to be played during the callout. |
settings | Additionoal settings which are needed byt the call flow logic. |
Response
location: /api/callouts/212
201 Created
{
"id": 212,
"status": "initialized",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
},
"created_at": "2024-04-05T07:32:23.135Z",
"updated_at": "2024-04-05T07:32:23.135Z",
"account_id": 440,
"audio_url": "https://www.example.com/sample.mp3",
"settings": {
"external_service_1": {
"foo": "bar"
}
},
"created_by_id": null
}
Create a Callout Event
Request
curl "https://scfm.somleng.org/api/callouts/217/callout_events" -d '{
"event": "start"
}' -X POST \
-H "Authorization: Bearer 4tCj59t5thP2s6ZpgSNj3BWU7qLw4h-lZ3Z2BND4RA8"
Endpoint
POST /api/callouts/:callout_id/callout_events
POST /api/callouts/217/callout_events
Parameters
{
"event": "start"
}
Name | Description |
---|---|
event required | One of: start , pause , resume , stop |
Response
location: /api/callouts/217
201 Created
{
"account_id": 445,
"id": 217,
"status": "running",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
},
"created_at": "2024-04-05T07:32:23.219Z",
"updated_at": "2024-04-05T07:32:23.229Z",
"audio_url": null,
"settings": {
},
"created_by_id": null
}
Delete a Callout
Request
curl "https://scfm.somleng.org/api/callouts/215" -d '' -X DELETE \
-H "Authorization: Bearer y3reqGBNQonJTOkrvY_LJnlxECBnMlzQMUV-0pC7ywc"
Endpoint
DELETE /api/callouts/:id
DELETE /api/callouts/215
Parameters
None known.
Response
location: /api/callouts
204 No Content
List all Callouts
Request
curl -g "https://scfm.somleng.org/api/callouts?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer 5PPJOLgZPBRGGGXL88OWQssIHWXQL9hm8D02p0FebA4"
Endpoint
GET /api/callouts
GET /api/callouts?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 207,
"status": "initialized",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
"foo": "bar"
},
"created_at": "2024-04-05T07:32:23.084Z",
"updated_at": "2024-04-05T07:32:23.084Z",
"account_id": 437,
"audio_url": null,
"settings": {
},
"created_by_id": null
}
]
Retrieve a Callout
Request
curl -g "https://scfm.somleng.org/api/callouts/213" -X GET \
-H "Authorization: Bearer 5ghtNXznfwXL1dpoAVDResUIwrkSAP9AO41VRofp8So"
Endpoint
GET /api/callouts/:id
GET /api/callouts/213
Parameters
None known.
Response
location: /api/callouts/213
200 OK
{
"id": 213,
"status": "initialized",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"metadata": {
},
"created_at": "2024-04-05T07:32:23.143Z",
"updated_at": "2024-04-05T07:32:23.143Z",
"account_id": 441,
"audio_url": null,
"settings": {
},
"created_by_id": null
}
Update a Callout
Request
curl "https://scfm.somleng.org/api/callouts/214" -d '{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer 2xBP935NtHbnoff6loXmHJxCTP3UGENM3dF5bPoFHGU"
Endpoint
PATCH /api/callouts/:id
PATCH /api/callouts/214
Parameters
{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/callouts/214
204 No Content
Contacts
Create a Contact
Request
curl "https://scfm.somleng.org/api/contacts" -d '{
"msisdn": "252662346010",
"metadata": {
"gender": "f",
"name": "Kate"
}
}' -X POST \
-H "Authorization: Bearer fwEYUO5lb9TVA9wu3baz8J2ZDkdZPPsgRFUBjjroAHM"
Endpoint
POST /api/contacts
POST /api/contacts
Parameters
{
"msisdn": "252662346010",
"metadata": {
"gender": "f",
"name": "Kate"
}
}
Name | Description |
---|---|
msisdn required | Phone number in E.164 format |
Response
location: /api/contacts/220
201 Created
{
"id": 220,
"msisdn": "+252662346010",
"metadata": {
"gender": "f",
"name": "Kate"
},
"created_at": "2024-04-05T07:32:23.342Z",
"updated_at": "2024-04-05T07:32:23.342Z",
"account_id": 452
}
Create or update a Contact
Creates or updates a contact. If a contact is found with the msisdn
, it is updated, otherwise it is created.
Request
curl "https://scfm.somleng.org/api/contact_data" -d '{
"msisdn": "252662346014",
"metadata": {
"gender": "f",
"name": "Kate"
}
}' -X POST \
-H "Authorization: Bearer UfkB3HGKrNlvUJkQzf24yCA6W4GHsgyqvSicmPuzIag"
Endpoint
POST /api/contact_data
POST /api/contact_data
Parameters
{
"msisdn": "252662346014",
"metadata": {
"gender": "f",
"name": "Kate"
}
}
None known.
Response
location: /api/contacts/224
201 Created
{
"id": 224,
"msisdn": "+252662346014",
"metadata": {
"gender": "f",
"name": "Kate"
},
"created_at": "2024-04-05T07:32:23.412Z",
"updated_at": "2024-04-05T07:32:23.412Z",
"account_id": 457
}
Delete a Contact
Request
curl "https://scfm.somleng.org/api/contacts/226" -d '' -X DELETE \
-H "Authorization: Bearer zJKS-LiT8LHbyz0Qvd2F-D0wTrogn3ubXKPaUW_vVo0"
Endpoint
DELETE /api/contacts/:id
DELETE /api/contacts/226
Parameters
None known.
Response
location: /api/contacts
204 No Content
Filter contacts by metadata
Filters contacts by the metadata provided in the query.
Available operators: in, any, lt, lteq, gt, gteq, exists
Request
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][registered_districts.any][]=1402&q[metadata][registered_districts.any][]=1401" -X GET \
-H "Authorization: Bearer ZHDMg8Si3dODCvZT-Ed7hg8Fx-Xr0xEj1Qen0-9ngNc"
Endpoint
GET /api/contacts
GET /api/contacts?q[metadata][registered_districts.any][]=1402&q[metadata][registered_districts.any][]=1401
Parameters
q: {"metadata"=>{"registered_districts.any"=>["1402", "1401"]}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 216,
"msisdn": "+252662346006",
"metadata": {
"registered_districts": [
"1401"
]
},
"created_at": "2024-04-05T07:32:23.295Z",
"updated_at": "2024-04-05T07:32:23.295Z",
"account_id": 450
}
]
List all Contacts
Request
curl -g "https://scfm.somleng.org/api/contacts" -X GET \
-H "Authorization: Bearer TWYkwCH_GQMWOC5GezjXtJYpL1iDvWwJm0pcViAjdWY"
Endpoint
GET /api/contacts
GET /api/contacts
Parameters
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 214,
"msisdn": "+252662346004",
"metadata": {
},
"created_at": "2024-04-05T07:32:23.273Z",
"updated_at": "2024-04-05T07:32:23.273Z",
"account_id": 448
}
]
Retrieve a Contact
Request
curl -g "https://scfm.somleng.org/api/contacts/221" -X GET \
-H "Authorization: Bearer 7jDqmcYFci-6-toySNKy3SO2msJT6LQjq-mNpKLNk5Y"
Endpoint
GET /api/contacts/:id
GET /api/contacts/221
Parameters
None known.
Response
location: /api/contacts/221
200 OK
{
"id": 221,
"msisdn": "+252662346011",
"metadata": {
},
"created_at": "2024-04-05T07:32:23.363Z",
"updated_at": "2024-04-05T07:32:23.363Z",
"account_id": 454
}
Update a Contact
Request
curl "https://scfm.somleng.org/api/contacts/222" -d '{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer FRc0gPWf_wqrlNG2IDF4fZD9yLaKJOOFVXusNzqtYAk"
Endpoint
PATCH /api/contacts/:id
PATCH /api/contacts/222
Parameters
{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/contacts/222
204 No Content
Phone Calls
List all Phone Calls
Request
curl -g "https://scfm.somleng.org/api/phone_calls?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer y5wsL0rBypbqcE3-DK0AEvFZzKk5fMvlxmaM3sUOuG8"
Endpoint
GET /api/phone_calls
GET /api/phone_calls?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 147,
"callout_participation_id": 174,
"contact_id": 229,
"status": "created",
"msisdn": "+252662346019",
"remote_call_id": "186e1a72-1979-4cae-a1d7-3b34c9e34006",
"remote_status": null,
"remote_direction": null,
"remote_error_message": null,
"metadata": {
"foo": "bar"
},
"remote_response": {
},
"remote_queue_response": {
},
"call_flow_logic": "CallFlowLogic::HelloWorld",
"remotely_queued_at": null,
"created_at": "2024-04-05T07:32:23.488Z",
"updated_at": "2024-04-05T07:32:23.488Z",
"duration": 0,
"lock_version": 0,
"account_id": 461,
"remote_status_fetch_queued_at": null,
"callout_id": 222
}
]
Retrieve a Phone Call
Request
curl -g "https://scfm.somleng.org/api/phone_calls/156" -X GET \
-H "Authorization: Bearer jp9qUnjQP5-l_3SAzXYVtsb8ndtj5xnex_ZKfJwW0x4"
Endpoint
GET /api/phone_calls/:id
GET /api/phone_calls/156
Parameters
None known.
Response
location: /api/phone_calls/156
200 OK
{
"id": 156,
"callout_participation_id": 183,
"contact_id": 238,
"status": "created",
"msisdn": "+252662346028",
"remote_call_id": "6cf67fd2-e5ff-42f1-b440-faebd405777f",
"remote_status": null,
"remote_direction": null,
"remote_error_message": null,
"metadata": {
},
"remote_response": {
},
"remote_queue_response": {
},
"call_flow_logic": "CallFlowLogic::HelloWorld",
"remotely_queued_at": null,
"created_at": "2024-04-05T07:32:23.654Z",
"updated_at": "2024-04-05T07:32:23.654Z",
"duration": 0,
"lock_version": 0,
"account_id": 467,
"remote_status_fetch_queued_at": null,
"callout_id": 231
}
Recordings
List Recordings
Request
curl -g "https://scfm.somleng.org/api/recordings?q[created_at_or_after]=2024-04-05T07%3A32%3A23Z" -X GET \
-H "Authorization: Bearer IeWQ0cTH8SEFchq-F8Qpu-LSLIFLGa04ryXXWxIA_Qw"
Endpoint
GET /api/recordings
GET /api/recordings?q[created_at_or_after]=2024-04-05T07%3A32%3A23Z
Parameters
q: {"created_at_or_after"=>"2024-04-05T07:32:23Z"}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 1,
"phone_call_id": 157,
"account_id": 468,
"contact_id": 239,
"external_recording_id": "f40dee16-e6fd-4c79-a117-9695f020ba5a",
"external_recording_url": "https://api.somleng.org/2010-04-01/Accounts/6384bb87-2bec-414d-9484-7611ca74eb74/Calls/823c54c6-a639-4716-be69-aac28f3b28bc/Recordings/f40dee16-e6fd-4c79-a117-9695f020ba5a",
"duration": 15,
"created_at": "2024-04-05T07:32:23.709Z",
"updated_at": "2024-04-05T07:32:23.715Z"
}
]
Retrieve a Recording
Request
curl -g "https://scfm.somleng.org/api/recordings/4" -X GET \
-H "Authorization: Bearer YnDERDnm3FscLjDkdKTec6gJwpcxFPov9V4Le76Og6c"
Endpoint
GET /api/recordings/:id
GET /api/recordings/4
Parameters
None known.
Response
location: /api/recordings/4
200 OK
{
"id": 4,
"phone_call_id": 160,
"account_id": 476,
"contact_id": 242,
"external_recording_id": "ede5b819-49cd-48b1-a043-ee367a43393b",
"external_recording_url": "https://api.somleng.org/2010-04-01/Accounts/50770e93-6adf-4a2e-bacb-9802600240e7/Calls/10ea058c-61a0-4beb-933f-ad344a8f6eba/Recordings/ede5b819-49cd-48b1-a043-ee367a43393b",
"duration": 15,
"created_at": "2024-04-05T07:32:23.831Z",
"updated_at": "2024-04-05T07:32:23.836Z"
}
Retrieve a recording as mp3
Request
curl -g "https://scfm.somleng.orgapi/recordings/5.mp3" -X GET \
-H "Authorization: Bearer F7tUQT29BtHvo3pIWSH-OHd9dnnUJMVpERWR5WE4MOo"
Endpoint
GET api/recordings/:id.mp3
GET api/recordings/5.mp3
Parameters
None known.
Response
location: http://example.org/rails/active_storage/disk/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdDVG9JYTJWNVNTSWhjM0ZqY210dVpXUjNielUxY3pReFptYzBiR0ptWkd0dWVtNXNjQVk2QmtWVU9oQmthWE53YjNOcGRHbHZia2tpUDJGMGRHRmphRzFsYm5RN0lHWnBiR1Z1WVcxbFBTSjBaWE4wTG0xd015STdJR1pwYkdWdVlXMWxLajFWVkVZdE9DY25kR1Z6ZEM1dGNETUdPd1pVT2hGamIyNTBaVzUwWDNSNWNHVkpJZzloZFdScGJ5OXRjR1ZuQmpzR1ZEb1JjMlZ5ZG1salpWOXVZVzFsT2dsMFpYTjAiLCJleHAiOiIyMDI0LTA0LTA1VDA3OjM3OjIzLjkwNFoiLCJwdXIiOiJibG9iX2tleSJ9fQ==--bad532e443a2c3c02df3efd09e9b0cd469f6c3bf/test.mp3
302 Found
Remote Phone Call Events
Remote Phone Call Events are created by Somleng or Twilio Webhooks,
when an event happens in a Phone Call. Setup your Somleng or Twilio Webhook endpoint to point to
/api/remote_phone_call_events
List all Remote Phone Call Events
Request
curl -g "https://scfm.somleng.org/api/remote_phone_call_events?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer TiybM-CEGBvKvMqMkBJ6CGkzv8PdaDc9IJSV616oJlc"
Endpoint
GET /api/remote_phone_call_events
GET /api/remote_phone_call_events?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 77,
"phone_call_id": 162,
"details": {
"To": "345",
"From": "252662346035",
"CallSid": "5b8e4523-01ff-4794-9af4-736cdaad5ce4",
"Direction": "inbound",
"AccountSid": "90464f56-2bcd-48a3-874d-5491b7b14e6c",
"ApiVersion": "2010-04-01",
"CallStatus": "completed"
},
"metadata": {
"foo": "bar"
},
"remote_call_id": "5b8e4523-01ff-4794-9af4-736cdaad5ce4",
"remote_direction": "inbound",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"created_at": "2024-04-05T07:32:23.922Z",
"updated_at": "2024-04-05T07:32:23.922Z",
"call_duration": 0
}
]
Retrieve a Remote Phone Call Event
Request
curl -g "https://scfm.somleng.org/api/remote_phone_call_events/88" -X GET \
-H "Authorization: Bearer ZSR4b_pDrbRfEyLHEIs27gDqytyz8inF_XRPkeCB00c"
Endpoint
GET /api/remote_phone_call_events/:id
GET /api/remote_phone_call_events/88
Parameters
None known.
Response
location: /api/remote_phone_call_events/88
200 OK
{
"id": 88,
"phone_call_id": 173,
"details": {
"To": "345",
"From": "252662346057",
"CallSid": "0d9d2a4c-00dd-451d-b983-7c7ec019047f",
"Direction": "inbound",
"AccountSid": "875537e8-50fe-4578-bc28-f9ef10dff794",
"ApiVersion": "2010-04-01",
"CallStatus": "completed"
},
"metadata": {
},
"remote_call_id": "0d9d2a4c-00dd-451d-b983-7c7ec019047f",
"remote_direction": "inbound",
"call_flow_logic": "CallFlowLogic::HelloWorld",
"created_at": "2024-04-05T07:32:24.144Z",
"updated_at": "2024-04-05T07:32:24.144Z",
"call_duration": 0
}
Update a Remote Phone Call Event
Request
curl "https://scfm.somleng.org/api/remote_phone_call_events/89" -d '{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer qyCLrmA_YD1X5YImULv6hsLBz_T96QdeFIfT-iVUdfE"
Endpoint
PATCH /api/remote_phone_call_events/:id
PATCH /api/remote_phone_call_events/89
Parameters
{
"metadata": {
"foo": "bar"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/remote_phone_call_events/89
204 No Content
Shared API Features
Filtering, Sorting and Pagination
All index requests can be filtered and sorted by using the q
and sort
parameters.
Responses are paginated. The maxiumum number of items displayed for a single request is 25.
This can be verified by the Per-Page
response header. The actual number of items will appear in the Total
header.
If there are more than 25 items then you'll see a Link
header with links to the
first
, last
, next
and previous
pages.
The links are formatted according to RFC-8288.
Request
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][gender]=f&q[metadata][date_of_birth.date.gt]=2022-01-01&q[metadata][date_of_birth.date.lt]=2022-02-01&q[created_at_after]=2024-04-04&sort=-id%2Ccreated_at" -X GET \
-H "Authorization: Bearer BYyTPgr9HgU_2hSam_Bxawym_JiEw3mnkUvO_noRV0I"
Endpoint
GET /api/contacts
GET /api/contacts?q[metadata][gender]=f&q[metadata][date_of_birth.date.gt]=2022-01-01&q[metadata][date_of_birth.date.lt]=2022-02-01&q[created_at_after]=2024-04-04&sort=-id%2Ccreated_at
Parameters
q: {"metadata"=>{"gender"=>"f", "date_of_birth.date.gt"=>"2022-01-01", "date_of_birth.date.lt"=>"2022-02-01"}, "created_at_after"=>"2024-04-04"}
sort: -id,created_at
Name | Description |
---|---|
q | A filter in which to filter resources. You can always filter by metadata , created_at and updated_at . Additional filters are available different resources |
sort | A comma separated list of sort columns. For example to sort by id in descending order, then by created_at in ascending order, specify sort: -id,created_at |
Response
per-page: 25
total: 26
200 OK
[
{
"id": 282,
"msisdn": "+252662346085",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.249Z",
"updated_at": "2024-04-05T07:32:24.249Z",
"account_id": 488
},
{
"id": 281,
"msisdn": "+252662346084",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.247Z",
"updated_at": "2024-04-05T07:32:24.247Z",
"account_id": 488
},
{
"id": 280,
"msisdn": "+252662346083",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.244Z",
"updated_at": "2024-04-05T07:32:24.244Z",
"account_id": 488
},
{
"id": 279,
"msisdn": "+252662346082",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.242Z",
"updated_at": "2024-04-05T07:32:24.242Z",
"account_id": 488
},
{
"id": 278,
"msisdn": "+252662346081",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.240Z",
"updated_at": "2024-04-05T07:32:24.240Z",
"account_id": 488
},
{
"id": 277,
"msisdn": "+252662346080",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.237Z",
"updated_at": "2024-04-05T07:32:24.237Z",
"account_id": 488
},
{
"id": 276,
"msisdn": "+252662346079",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.235Z",
"updated_at": "2024-04-05T07:32:24.235Z",
"account_id": 488
},
{
"id": 275,
"msisdn": "+252662346078",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.232Z",
"updated_at": "2024-04-05T07:32:24.232Z",
"account_id": 488
},
{
"id": 274,
"msisdn": "+252662346077",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.230Z",
"updated_at": "2024-04-05T07:32:24.230Z",
"account_id": 488
},
{
"id": 273,
"msisdn": "+252662346076",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.228Z",
"updated_at": "2024-04-05T07:32:24.228Z",
"account_id": 488
},
{
"id": 272,
"msisdn": "+252662346075",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.225Z",
"updated_at": "2024-04-05T07:32:24.225Z",
"account_id": 488
},
{
"id": 271,
"msisdn": "+252662346074",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.223Z",
"updated_at": "2024-04-05T07:32:24.223Z",
"account_id": 488
},
{
"id": 270,
"msisdn": "+252662346073",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.220Z",
"updated_at": "2024-04-05T07:32:24.220Z",
"account_id": 488
},
{
"id": 269,
"msisdn": "+252662346072",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.218Z",
"updated_at": "2024-04-05T07:32:24.218Z",
"account_id": 488
},
{
"id": 268,
"msisdn": "+252662346071",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.216Z",
"updated_at": "2024-04-05T07:32:24.216Z",
"account_id": 488
},
{
"id": 267,
"msisdn": "+252662346070",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.213Z",
"updated_at": "2024-04-05T07:32:24.213Z",
"account_id": 488
},
{
"id": 266,
"msisdn": "+252662346069",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.211Z",
"updated_at": "2024-04-05T07:32:24.211Z",
"account_id": 488
},
{
"id": 265,
"msisdn": "+252662346068",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.208Z",
"updated_at": "2024-04-05T07:32:24.208Z",
"account_id": 488
},
{
"id": 264,
"msisdn": "+252662346067",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.206Z",
"updated_at": "2024-04-05T07:32:24.206Z",
"account_id": 488
},
{
"id": 263,
"msisdn": "+252662346066",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.203Z",
"updated_at": "2024-04-05T07:32:24.203Z",
"account_id": 488
},
{
"id": 262,
"msisdn": "+252662346065",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.201Z",
"updated_at": "2024-04-05T07:32:24.201Z",
"account_id": 488
},
{
"id": 261,
"msisdn": "+252662346064",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.199Z",
"updated_at": "2024-04-05T07:32:24.199Z",
"account_id": 488
},
{
"id": 260,
"msisdn": "+252662346063",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.196Z",
"updated_at": "2024-04-05T07:32:24.196Z",
"account_id": 488
},
{
"id": 259,
"msisdn": "+252662346062",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.194Z",
"updated_at": "2024-04-05T07:32:24.194Z",
"account_id": 488
},
{
"id": 258,
"msisdn": "+252662346061",
"metadata": {
"gender": "f",
"date_of_birth": "2022-01-15"
},
"created_at": "2024-04-05T07:32:24.191Z",
"updated_at": "2024-04-05T07:32:24.191Z",
"account_id": 488
}
]
Metadata
Metadata is useful for storing additional,
structured information on an object.
As an example, you could store the contact's name and gender on the Contact
object.
Request
curl "https://scfm.somleng.org/api/contacts/284" -d '{
"metadata": {
"name": "Kate"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer 6Rl7l5lqi1WeC_ir8GwZa8V-TVQ2TtkbIIicwWR_eUk"
Endpoint
PATCH /api/contacts/:id
PATCH /api/contacts/284
Parameters
{
"metadata": {
"name": "Kate"
},
"metadata_merge_mode": "replace"
}
Name | Description |
---|---|
metadata | Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. |
metadata_merge_mode | One of: merge (default), replace or deep_merge . merge merges the new metadata with the existing metadata. replace replaces the existing metadata with the new metadata. deep_merge deep merges the existing metadata with the new metadata. |
Response
location: /api/contacts/284
204 No Content
Users
Create a User
Request
curl "https://scfm.somleng.org/api/users" -d '{
"email": "user22@example.com",
"password": "secret123",
"metadata": {
"foo": "bar"
}
}' -X POST \
-H "Authorization: Bearer hSlQDwO2yd8BIhimuZPY8Q5J7E5qPUDO1zjDvJvfCi4"
Endpoint
POST /api/users
POST /api/users
Parameters
{
"email": "user22@example.com",
"password": "secret123",
"metadata": {
"foo": "bar"
}
}
Name | Description |
---|---|
email required | The email address of the user |
password required | The initial password of the user. The user can change their password when they log in. |
Response
location: /api/users/15
201 Created
{
"id": 15,
"account_id": 494,
"metadata": {
"foo": "bar"
},
"email": "user22@example.com",
"created_at": "2024-04-05T07:32:24.350Z",
"updated_at": "2024-04-05T07:32:24.350Z",
"locale": "en"
}
Create a User Event
Request
curl "https://scfm.somleng.org/api/users/20/user_events" -d '{
"event": "invite"
}' -X POST \
-H "Authorization: Bearer BMDLIgTsD7St2hMFsTOibSAB9QQPrUicLzrA7PuCbuM"
Endpoint
POST /api/users/:user_id/user_events
POST /api/users/20/user_events
Parameters
{
"event": "invite"
}
Name | Description |
---|---|
event required | Only invite is supported at this time |
Response
location: /api/users/20
201 Created
{
"account_id": 500,
"id": 20,
"metadata": {
},
"email": "user27@example.com",
"created_at": "2024-04-05T07:32:24.436Z",
"updated_at": "2024-04-05T07:32:24.444Z",
"locale": "en"
}
Delete a User
Request
curl "https://scfm.somleng.org/api/users/19" -d '' -X DELETE \
-H "Authorization: Bearer STcIasrA1mPyO4o4qfb-PCIv5M7zc9c-jl2YrBmdJtA"
Endpoint
DELETE /api/users/:id
DELETE /api/users/19
Parameters
None known.
Response
location: /api/users
204 No Content
List all Users
Request
curl -g "https://scfm.somleng.org/api/users?q[metadata][foo]=bar" -X GET \
-H "Authorization: Bearer 0xcFYT-Y58spBRWanKXpvMG6kyCbq3o2U7i4CaPJv-E"
Endpoint
GET /api/users
GET /api/users?q[metadata][foo]=bar
Parameters
q: {"metadata"=>{"foo"=>"bar"}}
None known.
Response
per-page: 25
total: 1
200 OK
[
{
"id": 10,
"account_id": 490,
"metadata": {
"foo": "bar"
},
"email": "user17@example.com",
"created_at": "2024-04-05T07:32:24.293Z",
"updated_at": "2024-04-05T07:32:24.293Z",
"locale": "en"
}
]
Retrieve a User
Request
curl -g "https://scfm.somleng.org/api/users/17" -X GET \
-H "Authorization: Bearer TnAJNyR4d4IjPEtUDg-DGtbcuJkb4KifvQyRcu1bfz8"
Endpoint
GET /api/users/:id
GET /api/users/17
Parameters
None known.
Response
location: /api/users/17
200 OK
{
"id": 17,
"account_id": 497,
"metadata": {
},
"email": "user24@example.com",
"created_at": "2024-04-05T07:32:24.380Z",
"updated_at": "2024-04-05T07:32:24.380Z",
"locale": "en"
}
Update a User
Request
curl "https://scfm.somleng.org/api/users/18" -d '{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}' -X PATCH \
-H "Authorization: Bearer 8fyeYJoIQVE8MtrkeiJg454P6_3bZNYj0P6t_DkAOWs"
Endpoint
PATCH /api/users/:id
PATCH /api/users/18
Parameters
{
"metadata": {
"bar": "foo"
},
"metadata_merge_mode": "replace"
}
None known.
Response
location: /api/users/18
204 No Content