NAV Navbar
JSON cURL

This is the API Documentation for Somleng Simple Call Flow Manager (Somleng SCFM).

Access Tokens

Create an Access Token

Request

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

Response

Location: /api/access_tokens/16
201 Created
{
  "id": 16,
  "token": "7hXQk2qo-981b4Ku-oVsIenUrhY4bbURlCL0EMWQe7Y",
  "created_at": "2019-12-13T02:05:51.039Z",
  "updated_at": "2019-12-13T02:05:51.040Z",
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}
curl "https://scfm.somleng.org/api/access_tokens" -d '{
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}' -X POST \
    -H "Authorization: Bearer eL-jEaoxu5dBA9PLfLL8G7S5yZKeyiphO0K1hbaiPCc"

Delete an Access Token

Request

Endpoint

DELETE /api/access_tokens/21

DELETE /api/access_tokens/:id

Parameters

None known.

Response

Location: /api/access_tokens
204 No Content
curl "https://scfm.somleng.org/api/access_tokens/21" -d '' -X DELETE \
    -H "Authorization: Bearer j1QStli4KgfLWGpT-voqh7GIxVJMF-LZlP8esVgkbTM"

List all Access Tokens

Request

Endpoint

GET /api/access_tokens?q[metadata][foo]=bar

GET /api/access_tokens

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": "Lxz2q4FOkHTxi6hwwTEq7ASO-dabGiE-MGJDRFotcP0",
    "created_at": "2019-12-13T02:05:50.902Z",
    "updated_at": "2019-12-13T02:05:50.903Z",
    "metadata": {
      "foo": "bar"
    },
    "permissions": [

    ]
  }
]
curl -g "https://scfm.somleng.org/api/access_tokens?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer fJYwQ2d6gRi6LnwBBbu5Hf-qX6bavw3OSE49wbzVreM"

Retrieve an Access Token

Request

Endpoint

GET /api/access_tokens/19

GET /api/access_tokens/:id

Parameters

None known.

Response

Location: /api/access_tokens/19
200 OK
{
  "id": 19,
  "token": "5jmliR03QPdvpEIZzs61WyoSO_PiM5wauBRcBZoeS7E",
  "created_at": "2019-12-13T02:05:51.076Z",
  "updated_at": "2019-12-13T02:05:51.077Z",
  "metadata": {
  },
  "permissions": [
    "access_tokens_read",
    "access_tokens_write"
  ]
}
curl -g "https://scfm.somleng.org/api/access_tokens/19" -X GET \
    -H "Authorization: Bearer 5jmliR03QPdvpEIZzs61WyoSO_PiM5wauBRcBZoeS7E"

Update an Access Token

Request

Endpoint

PATCH api/access_tokens/20

PATCH api/access_tokens/:id

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/access_tokens/20
204 No Content
curl "https://scfm.somleng.orgapi/access_tokens/20" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer o0dn4M3-a2WBw5GcVJyA76EnWtsI_lmdnJVCHnc29Lc"

Account Details

Retrieve Account Details

Request

Endpoint

GET /api/account

GET /api/account

Parameters

None known.

Response

Location: /api/accounts/488
200 OK
{
  "id": 488,
  "metadata": {
  },
  "settings": {
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2019-12-13T02:05:51.172Z",
  "updated_at": "2019-12-13T02:05:51.172Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}
curl -g "https://scfm.somleng.org/api/account" -X GET \
    -H "Authorization: Bearer zpEeUW0bdg_lFs7ezSWD2WPrV6M-dmjBoGPsBaaIbyw"

Update Account Details

Request

Endpoint

PATCH /api/account

PATCH /api/account

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/accounts/489
204 No Content
curl "https://scfm.somleng.org/api/account" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer 06ypXFx8IRnKGzEbIvGKInhSsvBYbP3Az3nYIt1SdrU"

Accounts

Only super admins can manage accounts.

Create an Account

Request

Endpoint

POST /api/accounts

POST /api/accounts

Parameters

None known.

Response

Location: /api/accounts/494
201 Created
{
  "id": 494,
  "metadata": {
  },
  "settings": {
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2019-12-13T02:05:51.274Z",
  "updated_at": "2019-12-13T02:05:51.274Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}
curl "https://scfm.somleng.org/api/accounts" -d '' -X POST \
    -H "Authorization: Bearer YyK6jKszos_k2EKZ3iPvDrWpF2mDQaVgLPaZmfTSuQU"

Delete an Account

Request

Endpoint

DELETE /api/accounts/499

DELETE /api/accounts/:id

Parameters

None known.

Response

Location: /api/accounts
204 No Content
curl "https://scfm.somleng.org/api/accounts/499" -d '' -X DELETE \
    -H "Authorization: Bearer iCpjOMV4l00ZywNu8Pa86QqB2BgsQP-i7LMCAe-GeG0"

List all Accounts

Request

Endpoint

GET /api/accounts?q[metadata][foo]=bar

GET /api/accounts

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 490,
    "metadata": {
      "foo": "bar"
    },
    "settings": {
    },
    "twilio_account_sid": null,
    "somleng_account_sid": null,
    "twilio_auth_token": null,
    "somleng_auth_token": null,
    "permissions": [

    ],
    "created_at": "2019-12-13T02:05:51.220Z",
    "updated_at": "2019-12-13T02:05:51.220Z",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "platform_provider_name": null,
    "somleng_api_host": null,
    "somleng_api_base_url": null
  }
]
curl -g "https://scfm.somleng.org/api/accounts?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer 3Uelm7BCBGJxG7L1sDKpF4tghPk1Uqy49udnZEZqQEw"

Retrieve an Account

Request

Endpoint

GET /api/accounts/495

GET /api/accounts/:id

Parameters

None known.

Response

Location: /api/accounts/495
200 OK
{
  "id": 495,
  "metadata": {
  },
  "settings": {
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2019-12-13T02:05:51.280Z",
  "updated_at": "2019-12-13T02:05:51.280Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}
curl -g "https://scfm.somleng.org/api/accounts/495" -X GET \
    -H "Authorization: Bearer 4mbi7wnLOwdwHChSr6GXHsDN78DhWGxHw3TOSxYmvs0"

Update an Account

Request

Endpoint

PATCH /api/accounts/497

PATCH /api/accounts/:id

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "c218a33a-13b6-4302-a185-1dca089be1bd",
  "twilio_auth_token": "19fd89f2-8b00-4ba8-b292-c463d3026346",
  "somleng_auth_token": "07a131b9-fe06-4bbd-affd-4cd98fb39adc",
  "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/497
204 No Content
curl "https://scfm.somleng.org/api/accounts/497" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "c218a33a-13b6-4302-a185-1dca089be1bd",
  "twilio_auth_token": "19fd89f2-8b00-4ba8-b292-c463d3026346",
  "somleng_auth_token": "07a131b9-fe06-4bbd-affd-4cd98fb39adc",
  "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 ShWu3TaheswqfqaAmBg5sMtLyXbe0fTSL87Trykp_PY"

Batch Operations

Create Phone Calls

Create a batch operation for creating phone calls. Specify remote_request_params to provide the request parameters for the phone call. You can filter which phone calls will be created using callout_filter_params, contact_filter_params and callout_participation_filter_params.

Request

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "remote_request_params": {
      "url": "https://scfm.somleng.org/api/remote_phone_call_events",
      "from": "1234",
      "status_callback": "https://scfm.somleng.org/api/remote_phone_call_events"
    },
    "callout_filter_params": {
      "status": "running"
    },
    "callout_participation_filter_params": {
      "having_max_phone_calls_count": 3,
      "no_phone_calls_or_last_attempt": "not_answered,busy,failed"
    },
    "limit": 20
  },
  "type": "BatchOperation::PhoneCallCreate"
}
Name Description
type required One of: BatchOperation::CalloutPopulation, BatchOperation::PhoneCallCreate, BatchOperation::PhoneCallQueue, BatchOperation::PhoneCallQueueRemoteFetch
parameters Parameters for the batch operation. limit, specifies a limit to the number of operations that will occur in the batch operation. skip_validate_preview_presence turns off validation for creating batch operations which would not effect any resources
callout_id The id of the callout. Only applicable if the type is BatchOperation::CalloutPopulation

Response

Location: /api/batch_operations/74
201 Created
{
  "id": 74,
  "callout_id": null,
  "parameters": {
    "skip_validate_preview_presence": "1",
    "remote_request_params": {
      "url": "https://scfm.somleng.org/api/remote_phone_call_events",
      "from": "1234",
      "status_callback": "https://scfm.somleng.org/api/remote_phone_call_events"
    },
    "callout_filter_params": {
      "status": "running"
    },
    "callout_participation_filter_params": {
      "having_max_phone_calls_count": 3,
      "no_phone_calls_or_last_attempt": "not_answered,busy,failed"
    },
    "limit": 20
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2019-12-13T02:05:51.488Z",
  "updated_at": "2019-12-13T02:05:51.488Z",
  "account_id": 506,
  "type": "BatchOperation::PhoneCallCreate"
}
curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "remote_request_params": {
      "url": "https://scfm.somleng.org/api/remote_phone_call_events",
      "from": "1234",
      "status_callback": "https://scfm.somleng.org/api/remote_phone_call_events"
    },
    "callout_filter_params": {
      "status": "running"
    },
    "callout_participation_filter_params": {
      "having_max_phone_calls_count": 3,
      "no_phone_calls_or_last_attempt": "not_answered,busy,failed"
    },
    "limit": 20
  },
  "type": "BatchOperation::PhoneCallCreate"
}' -X POST \
    -H "Authorization: Bearer 2irrMq-bZREjJV3PggmvPXs__2ZM9OyurGZs7BR26w4"

Create a Batch Operation Event

Request

Endpoint

POST /api/batch_operations/81/batch_operation_events

POST /api/batch_operations/:batch_operation_id/batch_operation_events

Parameters

{
  "event": "queue"
}
Name Description
event required Either queue or requeue.

Response

Location: /api/batch_operations/81
201 Created
{
  "id": 81,
  "callout_id": 250,
  "parameters": {
  },
  "metadata": {
  },
  "status": "queued",
  "created_at": "2019-12-13T02:05:51.678Z",
  "updated_at": "2019-12-13T02:05:51.678Z",
  "account_id": 516,
  "type": "BatchOperation::CalloutPopulation"
}
curl "https://scfm.somleng.org/api/batch_operations/81/batch_operation_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer l3Mjg_hyEy8svCFgIwdNJy-FMyT3e3Yc6S-KFqVTeZY"

Delete a Batch Operation

Request

Endpoint

DELETE /api/batch_operations/79

DELETE /api/batch_operations/:id

Parameters

None known.

Response

Location: /api/batch_operations
204 No Content
curl "https://scfm.somleng.org/api/batch_operations/79" -d '' -X DELETE \
    -H "Authorization: Bearer VtS2oQcCO9xgpPGa3RK2zuxRyY8KOSNhyUVhlU6fTP4"

List all Batch Operations

Request

Endpoint

GET /api/batch_operations?q[metadata][foo]=bar

GET /api/batch_operations

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 70,
    "callout_id": 241,
    "parameters": {
    },
    "metadata": {
      "foo": "bar"
    },
    "status": "preview",
    "created_at": "2019-12-13T02:05:51.414Z",
    "updated_at": "2019-12-13T02:05:51.414Z",
    "account_id": 503,
    "type": "BatchOperation::CalloutPopulation"
  }
]
curl -g "https://scfm.somleng.org/api/batch_operations?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer 1_HJdi6qR2DrDwinU5mBpWsOkQTp4-klisHe7cb3s6E"

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

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "callout_id": 244,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}
Name Description
type required One of: BatchOperation::CalloutPopulation, BatchOperation::PhoneCallCreate, BatchOperation::PhoneCallQueue, BatchOperation::PhoneCallQueueRemoteFetch
parameters Parameters for the batch operation. limit, specifies a limit to the number of operations that will occur in the batch operation. skip_validate_preview_presence turns off validation for creating batch operations which would not effect any resources
callout_id The id of the callout. Only applicable if the type is BatchOperation::CalloutPopulation

Response

Location: /api/batch_operations/73
201 Created
{
  "id": 73,
  "callout_id": 244,
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2019-12-13T02:05:51.462Z",
  "updated_at": "2019-12-13T02:05:51.462Z",
  "account_id": 505,
  "type": "BatchOperation::CalloutPopulation"
}
curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "callout_id": 244,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}' -X POST \
    -H "Authorization: Bearer sF0usIOK_euzc0c-EhROpRGDlyv8AJLmvW_LH5e_4gk"

Preview a Batch Operation

Previews a Batch Operation. For example, you can preview a CalloutPopulation batch operation for which contacts will participate in a callout.

Request

Endpoint

GET /api/batch_operations/86/preview/contacts

GET /api/batch_operations/:batch_operation_id/preview/contacts

Parameters

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 230,
    "msisdn": "+252662345981",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-12-13T02:05:51.949Z",
    "updated_at": "2019-12-13T02:05:51.949Z",
    "account_id": 521
  }
]
curl -g "https://scfm.somleng.org/api/batch_operations/86/preview/contacts" -X GET \
    -H "Authorization: Bearer Fz8C52LJHoAsjv0ODntuY1nLxG05mHOh1KTrlRdBeck"

Queue Phone Calls

Create a batch operation for queuing phone calls to Somleng or Twilio. You can filter which phone calls will be queued using phone_call_filter_params, contact_filter_params, callout_participation_filter_params and callout_filter_params.

Request

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "created"
    },
    "limit": 20
  },
  "type": "BatchOperation::PhoneCallQueue"
}
Name Description
type required One of: BatchOperation::CalloutPopulation, BatchOperation::PhoneCallCreate, BatchOperation::PhoneCallQueue, BatchOperation::PhoneCallQueueRemoteFetch
parameters Parameters for the batch operation. limit, specifies a limit to the number of operations that will occur in the batch operation. skip_validate_preview_presence turns off validation for creating batch operations which would not effect any resources
callout_id The id of the callout. Only applicable if the type is BatchOperation::CalloutPopulation

Response

Location: /api/batch_operations/75
201 Created
{
  "id": 75,
  "callout_id": null,
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "created"
    },
    "limit": 20
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2019-12-13T02:05:51.514Z",
  "updated_at": "2019-12-13T02:05:51.514Z",
  "account_id": 507,
  "type": "BatchOperation::PhoneCallQueue"
}
curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "created"
    },
    "limit": 20
  },
  "type": "BatchOperation::PhoneCallQueue"
}' -X POST \
    -H "Authorization: Bearer JhSckpzZwuEW4R7P12Ix0LRS-3LQvaUCDUpF1r2Um3U"

Queue Remote Status Fetch

Create a batch operation for fetching the remote status of calls on Somleng or Twilio. You can filter which phone calls will be fetched using phone_call_filter_params, contact_filter_params, callout_participation_filter_params and callout_filter_params.

Request

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "remotely_queued,in_progress"
    },
    "limit": 200
  },
  "type": "BatchOperation::PhoneCallQueueRemoteFetch"
}
Name Description
type required One of: BatchOperation::CalloutPopulation, BatchOperation::PhoneCallCreate, BatchOperation::PhoneCallQueue, BatchOperation::PhoneCallQueueRemoteFetch
parameters Parameters for the batch operation. limit, specifies a limit to the number of operations that will occur in the batch operation. skip_validate_preview_presence turns off validation for creating batch operations which would not effect any resources
callout_id The id of the callout. Only applicable if the type is BatchOperation::CalloutPopulation

Response

Location: /api/batch_operations/76
201 Created
{
  "id": 76,
  "callout_id": null,
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "remotely_queued,in_progress"
    },
    "limit": 200
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2019-12-13T02:05:51.535Z",
  "updated_at": "2019-12-13T02:05:51.535Z",
  "account_id": 508,
  "type": "BatchOperation::PhoneCallQueueRemoteFetch"
}
curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "callout_filter_params": {
      "status": "running"
    },
    "phone_call_filter_params": {
      "status": "remotely_queued,in_progress"
    },
    "limit": 200
  },
  "type": "BatchOperation::PhoneCallQueueRemoteFetch"
}' -X POST \
    -H "Authorization: Bearer dTayjK7Cu2XO3LudO5tSnoDNvyuzg05gFsrrUdjwmSk"

Retrieve a Batch Operation

Request

Endpoint

GET /api/batch_operations/77

GET /api/batch_operations/:id

Parameters

None known.

Response

Location: /api/batch_operations/77
200 OK
{
  "id": 77,
  "callout_id": 245,
  "parameters": {
  },
  "metadata": {
  },
  "status": "preview",
  "created_at": "2019-12-13T02:05:51.567Z",
  "updated_at": "2019-12-13T02:05:51.567Z",
  "account_id": 510,
  "type": "BatchOperation::CalloutPopulation"
}
curl -g "https://scfm.somleng.org/api/batch_operations/77" -X GET \
    -H "Authorization: Bearer ma4bPN5jbo5P9F6KJpJI2rsRL_U6k5wO_qOiV_35oxQ"

Update a Batch Operation

Request

Endpoint

PATCH /api/batch_operations/78

PATCH /api/batch_operations/:id

Parameters

{
  "metadata": {
    "foo": "bar",
    "bar": "foo"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/batch_operations/78
204 No Content
curl "https://scfm.somleng.org/api/batch_operations/78" -d '{
  "metadata": {
    "foo": "bar",
    "bar": "foo"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer h386IHYq9qnVNUgYC9ENoT35MsZss70h2hFyG_bRbjQ"

Callout Participations

Create a Callout Participation

Request

Endpoint

POST /api/callouts/276/callout_participations

POST /api/callouts/:callout_id/callout_participations

Parameters

{
  "contact_id": 251,
  "msisdn": "252662346003",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}

None known.

Response

Location: /api/callout_participations/230
201 Created
{
  "id": 230,
  "callout_id": 276,
  "contact_id": 251,
  "callout_population_id": null,
  "msisdn": "+252662346003",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2019-12-13T02:05:52.414Z",
  "updated_at": "2019-12-13T02:05:52.414Z"
}
curl "https://scfm.somleng.org/api/callouts/276/callout_participations" -d '{
  "contact_id": 251,
  "msisdn": "252662346003",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer 2JqjblheWi5BJXs9LLuQ8Zx9s4PgaMoM1XdtDOs8_ao"

Create a Callout Participation with invalid data

Request

Endpoint

POST /api/callouts/277/callout_participations

POST /api/callouts/:callout_id/callout_participations

Parameters

None known.

Response


422 Unprocessable Entity
{
  "errors": {
    "msisdn": [
      "can't be blank"
    ],
    "contact": [
      "must exist"
    ]
  }
}
curl "https://scfm.somleng.org/api/callouts/277/callout_participations" -d '' -X POST \
    -H "Authorization: Bearer N7UMO6oKS1gs0jr6x8qf-2ogq1YALRljha6vkwGNU1M"

Delete a Callout Participation

Request

Endpoint

DELETE /api/callout_participations/233

DELETE /api/callout_participations/:id

Parameters

None known.

Response

Location: /api/callout_participations
204 No Content
curl "https://scfm.somleng.org/api/callout_participations/233" -d '' -X DELETE \
    -H "Authorization: Bearer ud02KhFaBSr4rJ8ZrwwBGKSX8rW4AqwU0fVcUE_lt-I"

Delete a Callout Participation with phone calls

Request

Endpoint

DELETE /api/callout_participations/234

DELETE /api/callout_participations/:id

Parameters

None known.

Response


422 Unprocessable Entity
{
  "errors": {
    "base": [
      "Cannot delete record because dependent phone calls exist"
    ]
  }
}
curl "https://scfm.somleng.org/api/callout_participations/234" -d '' -X DELETE \
    -H "Authorization: Bearer WF8_WIVmbakPW-wLrMzRKBlY5PrQ3dUJQ1UUlSx-Tzc"

List all Callout Participations

Request

Endpoint

GET /api/callout_participations?q[metadata][foo]=bar&q[having_max_phone_calls_count]=1

GET /api/callout_participations

Parameters

q: {"metadata"=>{"foo"=>"bar"}, "having_max_phone_calls_count"=>"1"}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 219,
    "callout_id": 264,
    "contact_id": 240,
    "callout_population_id": null,
    "msisdn": "+252662345991",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-12-13T02:05:52.169Z",
    "updated_at": "2019-12-13T02:05:52.169Z"
  }
]
curl -g "https://scfm.somleng.org/api/callout_participations?q[metadata][foo]=bar&q[having_max_phone_calls_count]=1" -X GET \
    -H "Authorization: Bearer 5cPr2lqqFsmMYpZJa5PLbntkDwcIMgd4yHKYS4aKXN0"

Retrieve a Callout Participation

Request

Endpoint

GET /api/callout_participations/231

GET /api/callout_participations/:id

Parameters

None known.

Response

Location: /api/callout_participations/231
200 OK
{
  "id": 231,
  "callout_id": 278,
  "contact_id": 252,
  "callout_population_id": null,
  "msisdn": "+252662346004",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-12-13T02:05:52.451Z",
  "updated_at": "2019-12-13T02:05:52.451Z"
}
curl -g "https://scfm.somleng.org/api/callout_participations/231" -X GET \
    -H "Authorization: Bearer EpJ9LYsXvZb5Vi46Jl2r9tR0Vw0GYkP8-Yi8hEptFL4"

Update a Callout Participation

Request

Endpoint

PATCH /api/callout_participations/232

PATCH /api/callout_participations/:id

Parameters

{
  "contact_id": 254,
  "msisdn": "252662346007",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/callout_participations/232
204 No Content
curl "https://scfm.somleng.org/api/callout_participations/232" -d '{
  "contact_id": 254,
  "msisdn": "252662346007",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer 0gp6UbPDvpcp-cwFWmjT2it_BSSMWlcR1Q1gDMOim-M"

Callouts

Create a Callout

Request

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/287
201 Created
{
  "id": 287,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2019-12-13T02:05:52.646Z",
  "updated_at": "2019-12-13T02:05:52.646Z",
  "account_id": 542,
  "audio_url": "https://www.example.com/sample.mp3",
  "settings": {
    "external_service_1": {
      "foo": "bar"
    }
  },
  "created_by_id": null
}
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 VGTk7YysSRdHaB1MY37pVEGOjWNtkp-PapAODPp3mMU"

Create a Callout Event

Request

Endpoint

POST /api/callouts/292/callout_events

POST /api/callouts/:callout_id/callout_events

Parameters

{
  "event": "start"
}
Name Description
event required One of: start, pause, resume, stop

Response

Location: /api/callouts/292
201 Created
{
  "account_id": 547,
  "id": 292,
  "status": "running",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-12-13T02:05:52.800Z",
  "updated_at": "2019-12-13T02:05:52.820Z",
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}
curl "https://scfm.somleng.org/api/callouts/292/callout_events" -d '{
  "event": "start"
}' -X POST \
    -H "Authorization: Bearer aIH9B9q_PqKi8Q6mVUDMGsvBqT1CSX1-OHKYBPwx7jw"

Delete a Callout

Request

Endpoint

DELETE /api/callouts/290

DELETE /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts
204 No Content
curl "https://scfm.somleng.org/api/callouts/290" -d '' -X DELETE \
    -H "Authorization: Bearer cZHISFejStNidS96R-DM4t0U-Fl75H5YWCzVvfW9xcY"

List all Callouts

Request

Endpoint

GET /api/callouts?q[metadata][foo]=bar

GET /api/callouts

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 282,
    "status": "initialized",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-12-13T02:05:52.569Z",
    "updated_at": "2019-12-13T02:05:52.569Z",
    "account_id": 539,
    "audio_url": null,
    "settings": {
    },
    "created_by_id": null
  }
]
curl -g "https://scfm.somleng.org/api/callouts?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer mC-0ZZw04JHWdLRHoJ87tEljHTzl13T_gbAEzkNWkww"

Retrieve a Callout

Request

Endpoint

GET /api/callouts/288

GET /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts/288
200 OK
{
  "id": 288,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-12-13T02:05:52.655Z",
  "updated_at": "2019-12-13T02:05:52.655Z",
  "account_id": 543,
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}
curl -g "https://scfm.somleng.org/api/callouts/288" -X GET \
    -H "Authorization: Bearer AdSdz_baqPO4SOdz-Q7Lr3hRBlX-A2Lu1arAzIRmpsg"

Update a Callout

Request

Endpoint

PATCH /api/callouts/289

PATCH /api/callouts/:id

Parameters

{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/callouts/289
204 No Content
curl "https://scfm.somleng.org/api/callouts/289" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer wkULRHqseftmevmJmo8ULMb4HhEFJWlY48LthKDK9Kg"

Contacts

Create a Contact

Request

Endpoint

POST /api/contacts

POST /api/contacts

Parameters

{
  "msisdn": "252662346021",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}
Name Description
msisdn required Phone number in E.164 format

Response

Location: /api/contacts/268
201 Created
{
  "id": 268,
  "msisdn": "+252662346021",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2019-12-13T02:05:53.057Z",
  "updated_at": "2019-12-13T02:05:53.057Z",
  "account_id": 555
}
curl "https://scfm.somleng.org/api/contacts" -d '{
  "msisdn": "252662346021",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer 7OZOrU9qrmSk9FWWSil888hfaGyj4rHT1Q-H6VDLElw"

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

Endpoint

POST /api/contact_data

POST /api/contact_data

Parameters

{
  "msisdn": "252662346025",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}

None known.

Response

Location: /api/contacts/272
201 Created
{
  "id": 272,
  "msisdn": "+252662346025",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2019-12-13T02:05:53.202Z",
  "updated_at": "2019-12-13T02:05:53.202Z",
  "account_id": 560
}
curl "https://scfm.somleng.org/api/contact_data" -d '{
  "msisdn": "252662346025",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer 2TyXL-2WgzVsfKwuNr8J2NVzQ5U1W7j6iZcip0BW9bM"

Delete a Contact

Request

Endpoint

DELETE /api/contacts/274

DELETE /api/contacts/:id

Parameters

None known.

Response

Location: /api/contacts
204 No Content
curl "https://scfm.somleng.org/api/contacts/274" -d '' -X DELETE \
    -H "Authorization: Bearer OizojjsqARRtWhbq9o07-A0GfoV5m0pUf5CIfWrqekA"

List all Contacts

Request

Endpoint

GET /api/contacts?q[metadata][foo]=bar

GET /api/contacts

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 259,
    "msisdn": "+252662346012",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-12-13T02:05:52.874Z",
    "updated_at": "2019-12-13T02:05:52.874Z",
    "account_id": 550
  }
]
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer dgpJTAy1Ua6mIeHVedosRwfzOMHzXtcPsYGn8ffPzTI"

Retrieve a Contact

Request

Endpoint

GET /api/contacts/269

GET /api/contacts/:id

Parameters

None known.

Response

Location: /api/contacts/269
200 OK
{
  "id": 269,
  "msisdn": "+252662346022",
  "metadata": {
  },
  "created_at": "2019-12-13T02:05:53.098Z",
  "updated_at": "2019-12-13T02:05:53.098Z",
  "account_id": 557
}
curl -g "https://scfm.somleng.org/api/contacts/269" -X GET \
    -H "Authorization: Bearer ZaYq3WHoUKCPu6waiEynfnonosZYzqFe-01giaaqjS0"

Update a Contact

Request

Endpoint

PATCH /api/contacts/270

PATCH /api/contacts/:id

Parameters

{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/contacts/270
204 No Content
curl "https://scfm.somleng.org/api/contacts/270" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer PA88mpYg3Y8U38KdCsGH2y4hWMrp9oAVuTRIGBB7pOQ"

Phone Calls

Create a Phone Call

Request

Endpoint

POST /api/callout_participations/257/phone_calls

POST /api/callout_participations/:callout_participation_id/phone_calls

Parameters

{
  "msisdn": "252662346046",
  "remote_request_params": {
    "to": "to",
    "from": "from",
    "method": "method",
    "fallback_url": "fallback_url",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "send_digits": "send_digits",
    "timeout": "timeout",
    "record": "record",
    "recording_channels": "recording_channels",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_method": "recording_status_callback_method",
    "sip_auth_username": "sip_auth_username",
    "sip_auth_password": "sip_auth_password",
    "machine_detection": "machine_detection",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback_event": "recording_status_callback_event",
    "trim": "trim",
    "caller_id": "caller_id",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "url": "url",
    "twiml": "twiml",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}
Name Description
callout_participation_id required The id of the callout participation
remote_request_params required The request parameters to send to Somleng or Twilio

Response

Location: /api/phone_calls/210
201 Created
{
  "id": 210,
  "callout_participation_id": 257,
  "contact_id": 292,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "created",
  "msisdn": "+252662346046",
  "remote_call_id": null,
  "remote_status": null,
  "remote_direction": null,
  "remote_error_message": null,
  "metadata": {
    "foo": "bar"
  },
  "remote_response": {
  },
  "remote_request_params": {
    "to": "to",
    "from": "from",
    "method": "method",
    "fallback_url": "fallback_url",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "send_digits": "send_digits",
    "timeout": "timeout",
    "record": "record",
    "recording_channels": "recording_channels",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_method": "recording_status_callback_method",
    "sip_auth_username": "sip_auth_username",
    "sip_auth_password": "sip_auth_password",
    "machine_detection": "machine_detection",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback_event": "recording_status_callback_event",
    "trim": "trim",
    "caller_id": "caller_id",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "url": "url",
    "twiml": "twiml",
    "application_sid": "application_sid"
  },
  "remote_queue_response": {
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "remotely_queued_at": null,
  "created_at": "2019-12-13T02:05:53.706Z",
  "updated_at": "2019-12-13T02:05:53.706Z",
  "duration": 0,
  "lock_version": 0,
  "account_id": 573
}
curl "https://scfm.somleng.org/api/callout_participations/257/phone_calls" -d '{
  "msisdn": "252662346046",
  "remote_request_params": {
    "to": "to",
    "from": "from",
    "method": "method",
    "fallback_url": "fallback_url",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "send_digits": "send_digits",
    "timeout": "timeout",
    "record": "record",
    "recording_channels": "recording_channels",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_method": "recording_status_callback_method",
    "sip_auth_username": "sip_auth_username",
    "sip_auth_password": "sip_auth_password",
    "machine_detection": "machine_detection",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback_event": "recording_status_callback_event",
    "trim": "trim",
    "caller_id": "caller_id",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "url": "url",
    "twiml": "twiml",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer DGZ2PQZvvjcX9hfMW0IKH2RolpNmEUYtQANC0o9-lKg"

Create a Phone Call Event

Queues a phone call, or a remote phone call status update on Somleng or Twilio

Request

Endpoint

POST /api/phone_calls/215/phone_call_events

POST /api/phone_calls/:phone_call_id/phone_call_events

Parameters

{
  "event": "queue"
}
Name Description
event required Either queue or queue_remote_fetch

Response

Location: /api/phone_calls/215
201 Created
{
  "account_id": 579,
  "id": 215,
  "callout_participation_id": 263,
  "contact_id": 298,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "queued",
  "msisdn": "+252662346054",
  "remote_call_id": null,
  "remote_status": null,
  "remote_direction": null,
  "remote_error_message": null,
  "metadata": {
  },
  "remote_response": {
  },
  "remote_request_params": {
    "to": "to",
    "url": "url",
    "from": "from",
    "trim": "trim",
    "twiml": "twiml",
    "method": "method",
    "record": "record",
    "timeout": "timeout",
    "caller_id": "caller_id",
    "send_digits": "send_digits",
    "fallback_url": "fallback_url",
    "application_sid": "application_sid",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "machine_detection": "machine_detection",
    "sip_auth_password": "sip_auth_password",
    "sip_auth_username": "sip_auth_username",
    "recording_channels": "recording_channels",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_event": "recording_status_callback_event",
    "recording_status_callback_method": "recording_status_callback_method",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold"
  },
  "remote_queue_response": {
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "remotely_queued_at": null,
  "created_at": "2019-12-13T02:05:53.890Z",
  "updated_at": "2019-12-13T02:05:53.911Z",
  "duration": 0,
  "lock_version": 1
}
curl "https://scfm.somleng.org/api/phone_calls/215/phone_call_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer AIVNj7O3ewj2vXU0G5YSYTQVE-odi-QmkR3arFWJe-s"

Delete a Phone Call

Request

Endpoint

DELETE /api/phone_calls/213

DELETE /api/phone_calls/:id

Parameters

None known.

Response

Location: /api/phone_calls
204 No Content
curl "https://scfm.somleng.org/api/phone_calls/213" -d '' -X DELETE \
    -H "Authorization: Bearer 3Z5LjsBKxJmH29j6NOWB3YeqKFXSDXDB9Bhw2LJ56kM"

List all Phone Calls

Request

Endpoint

GET /api/phone_calls?q[metadata][foo]=bar

GET /api/phone_calls

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 195,
    "callout_participation_id": 242,
    "contact_id": 277,
    "create_batch_operation_id": null,
    "queue_batch_operation_id": null,
    "queue_remote_fetch_batch_operation_id": null,
    "status": "created",
    "msisdn": "+252662346030",
    "remote_call_id": null,
    "remote_status": null,
    "remote_direction": null,
    "remote_error_message": null,
    "metadata": {
      "foo": "bar"
    },
    "remote_response": {
    },
    "remote_request_params": {
      "to": "to",
      "url": "url",
      "from": "from",
      "trim": "trim",
      "twiml": "twiml",
      "method": "method",
      "record": "record",
      "timeout": "timeout",
      "caller_id": "caller_id",
      "send_digits": "send_digits",
      "fallback_url": "fallback_url",
      "application_sid": "application_sid",
      "fallback_method": "fallback_method",
      "status_callback": "status_callback",
      "machine_detection": "machine_detection",
      "sip_auth_password": "sip_auth_password",
      "sip_auth_username": "sip_auth_username",
      "recording_channels": "recording_channels",
      "status_callback_event": "status_callback_event",
      "status_callback_method": "status_callback_method",
      "machine_detection_timeout": "machine_detection_timeout",
      "recording_status_callback": "recording_status_callback",
      "recording_status_callback_event": "recording_status_callback_event",
      "recording_status_callback_method": "recording_status_callback_method",
      "machine_detection_silence_timeout": "machine_detection_silence_timeout",
      "machine_detection_speech_threshold": "machine_detection_speech_threshold",
      "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold"
    },
    "remote_queue_response": {
    },
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "remotely_queued_at": null,
    "created_at": "2019-12-13T02:05:53.316Z",
    "updated_at": "2019-12-13T02:05:53.316Z",
    "duration": 0,
    "lock_version": 0,
    "account_id": 564
  }
]
curl -g "https://scfm.somleng.org/api/phone_calls?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer wSsnRx02xE9I8nwyrjt7i4vmUSM83Ajyevyo0P-keGc"

Retrieve a Phone Call

Request

Endpoint

GET /api/phone_calls/211

GET /api/phone_calls/:id

Parameters

None known.

Response

Location: /api/phone_calls/211
200 OK
{
  "id": 211,
  "callout_participation_id": 259,
  "contact_id": 294,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "created",
  "msisdn": "+252662346049",
  "remote_call_id": null,
  "remote_status": null,
  "remote_direction": null,
  "remote_error_message": null,
  "metadata": {
  },
  "remote_response": {
  },
  "remote_request_params": {
    "to": "to",
    "url": "url",
    "from": "from",
    "trim": "trim",
    "twiml": "twiml",
    "method": "method",
    "record": "record",
    "timeout": "timeout",
    "caller_id": "caller_id",
    "send_digits": "send_digits",
    "fallback_url": "fallback_url",
    "application_sid": "application_sid",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "machine_detection": "machine_detection",
    "sip_auth_password": "sip_auth_password",
    "sip_auth_username": "sip_auth_username",
    "recording_channels": "recording_channels",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_event": "recording_status_callback_event",
    "recording_status_callback_method": "recording_status_callback_method",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold"
  },
  "remote_queue_response": {
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "remotely_queued_at": null,
  "created_at": "2019-12-13T02:05:53.752Z",
  "updated_at": "2019-12-13T02:05:53.752Z",
  "duration": 0,
  "lock_version": 0,
  "account_id": 575
}
curl -g "https://scfm.somleng.org/api/phone_calls/211" -X GET \
    -H "Authorization: Bearer YWHe_As0Vb6gy-vil23A2S59XwuM8Zl5E1ZnT8Ldg3c"

Update a Phone Call

Request

Endpoint

PATCH /api/phone_calls/212

PATCH /api/phone_calls/:id

Parameters

{
  "msisdn": "252662346051",
  "remote_request_params": {
    "to": "to",
    "from": "from",
    "method": "method",
    "fallback_url": "fallback_url",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "send_digits": "send_digits",
    "timeout": "timeout",
    "record": "record",
    "recording_channels": "recording_channels",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_method": "recording_status_callback_method",
    "sip_auth_username": "sip_auth_username",
    "sip_auth_password": "sip_auth_password",
    "machine_detection": "machine_detection",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback_event": "recording_status_callback_event",
    "trim": "trim",
    "caller_id": "caller_id",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "url": "url",
    "twiml": "twiml",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/phone_calls/212
204 No Content
curl "https://scfm.somleng.org/api/phone_calls/212" -d '{
  "msisdn": "252662346051",
  "remote_request_params": {
    "to": "to",
    "from": "from",
    "method": "method",
    "fallback_url": "fallback_url",
    "fallback_method": "fallback_method",
    "status_callback": "status_callback",
    "status_callback_event": "status_callback_event",
    "status_callback_method": "status_callback_method",
    "send_digits": "send_digits",
    "timeout": "timeout",
    "record": "record",
    "recording_channels": "recording_channels",
    "recording_status_callback": "recording_status_callback",
    "recording_status_callback_method": "recording_status_callback_method",
    "sip_auth_username": "sip_auth_username",
    "sip_auth_password": "sip_auth_password",
    "machine_detection": "machine_detection",
    "machine_detection_timeout": "machine_detection_timeout",
    "recording_status_callback_event": "recording_status_callback_event",
    "trim": "trim",
    "caller_id": "caller_id",
    "machine_detection_speech_threshold": "machine_detection_speech_threshold",
    "machine_detection_speech_end_threshold": "machine_detection_speech_end_threshold",
    "machine_detection_silence_timeout": "machine_detection_silence_timeout",
    "url": "url",
    "twiml": "twiml",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer VdNuntE_I2VvLYsg-Ps8Tl-gCgj1o5hSgADV3RuquLI"

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

Endpoint

GET /api/remote_phone_call_events?q[metadata][foo]=bar

GET /api/remote_phone_call_events

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 34,
    "phone_call_id": 218,
    "details": {
      "To": "345",
      "From": "252662346058",
      "CallSid": "329941e3-a825-41c8-a8fd-5543f3c41c01",
      "Direction": "inbound",
      "AccountSid": "3d962146-a6e7-469c-8865-4a0b39fca335",
      "ApiVersion": "2010-04-01",
      "CallStatus": "completed"
    },
    "metadata": {
      "foo": "bar"
    },
    "remote_call_id": "329941e3-a825-41c8-a8fd-5543f3c41c01",
    "remote_direction": "inbound",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "created_at": "2019-12-13T02:05:54.060Z",
    "updated_at": "2019-12-13T02:05:54.060Z",
    "call_duration": 0
  }
]
curl -g "https://scfm.somleng.org/api/remote_phone_call_events?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer flqqbYHGvEWWvhjs3PfrCc8FfyIqjgOoUUiGKweNu78"

Retrieve a Remote Phone Call Event

Request

Endpoint

GET /api/remote_phone_call_events/45

GET /api/remote_phone_call_events/:id

Parameters

None known.

Response

Location: /api/remote_phone_call_events/45
200 OK
{
  "id": 45,
  "phone_call_id": 229,
  "details": {
    "To": "345",
    "From": "252662346080",
    "CallSid": "77e87fa3-1e0f-4254-9dea-c448224b2397",
    "Direction": "inbound",
    "AccountSid": "9005325f-378a-469b-9ffa-eaad0076f99e",
    "ApiVersion": "2010-04-01",
    "CallStatus": "completed"
  },
  "metadata": {
  },
  "remote_call_id": "77e87fa3-1e0f-4254-9dea-c448224b2397",
  "remote_direction": "inbound",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "created_at": "2019-12-13T02:05:54.310Z",
  "updated_at": "2019-12-13T02:05:54.310Z",
  "call_duration": 0
}
curl -g "https://scfm.somleng.org/api/remote_phone_call_events/45" -X GET \
    -H "Authorization: Bearer Nd_M1AfIeMAvGu4SMM38FiCXQUWH39RinkRHwsqbPrU"

Update a Remote Phone Call Event

Request

Endpoint

PATCH /api/remote_phone_call_events/46

PATCH /api/remote_phone_call_events/:id

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/remote_phone_call_events/46
204 No Content
curl "https://scfm.somleng.org/api/remote_phone_call_events/46" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer KHcxqrY0HesryJ80410SFYGoB44-aCtnEX34Slrc1VE"

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

Endpoint

GET /api/contacts?q[metadata][gender]=f&q[created_at_after]=2019-12-12&sort=-id%2Ccreated_at

GET /api/contacts

Parameters

q: {"metadata"=>{"gender"=>"f"}, "created_at_after"=>"2019-12-12"}
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": 342,
    "msisdn": "+252662346109",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.560Z",
    "updated_at": "2019-12-13T02:05:54.560Z",
    "account_id": 595
  },
  {
    "id": 341,
    "msisdn": "+252662346108",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.559Z",
    "updated_at": "2019-12-13T02:05:54.559Z",
    "account_id": 595
  },
  {
    "id": 340,
    "msisdn": "+252662346107",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.557Z",
    "updated_at": "2019-12-13T02:05:54.557Z",
    "account_id": 595
  },
  {
    "id": 339,
    "msisdn": "+252662346106",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.556Z",
    "updated_at": "2019-12-13T02:05:54.556Z",
    "account_id": 595
  },
  {
    "id": 338,
    "msisdn": "+252662346105",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.554Z",
    "updated_at": "2019-12-13T02:05:54.554Z",
    "account_id": 595
  },
  {
    "id": 337,
    "msisdn": "+252662346104",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.552Z",
    "updated_at": "2019-12-13T02:05:54.552Z",
    "account_id": 595
  },
  {
    "id": 336,
    "msisdn": "+252662346103",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.551Z",
    "updated_at": "2019-12-13T02:05:54.551Z",
    "account_id": 595
  },
  {
    "id": 335,
    "msisdn": "+252662346102",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.549Z",
    "updated_at": "2019-12-13T02:05:54.549Z",
    "account_id": 595
  },
  {
    "id": 334,
    "msisdn": "+252662346101",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.548Z",
    "updated_at": "2019-12-13T02:05:54.548Z",
    "account_id": 595
  },
  {
    "id": 333,
    "msisdn": "+252662346100",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.546Z",
    "updated_at": "2019-12-13T02:05:54.546Z",
    "account_id": 595
  },
  {
    "id": 332,
    "msisdn": "+252662346099",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.545Z",
    "updated_at": "2019-12-13T02:05:54.545Z",
    "account_id": 595
  },
  {
    "id": 331,
    "msisdn": "+252662346098",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.543Z",
    "updated_at": "2019-12-13T02:05:54.543Z",
    "account_id": 595
  },
  {
    "id": 330,
    "msisdn": "+252662346097",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.542Z",
    "updated_at": "2019-12-13T02:05:54.542Z",
    "account_id": 595
  },
  {
    "id": 329,
    "msisdn": "+252662346096",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.540Z",
    "updated_at": "2019-12-13T02:05:54.540Z",
    "account_id": 595
  },
  {
    "id": 328,
    "msisdn": "+252662346095",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.538Z",
    "updated_at": "2019-12-13T02:05:54.538Z",
    "account_id": 595
  },
  {
    "id": 327,
    "msisdn": "+252662346094",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.536Z",
    "updated_at": "2019-12-13T02:05:54.536Z",
    "account_id": 595
  },
  {
    "id": 326,
    "msisdn": "+252662346093",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.535Z",
    "updated_at": "2019-12-13T02:05:54.535Z",
    "account_id": 595
  },
  {
    "id": 325,
    "msisdn": "+252662346092",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.533Z",
    "updated_at": "2019-12-13T02:05:54.533Z",
    "account_id": 595
  },
  {
    "id": 324,
    "msisdn": "+252662346091",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.532Z",
    "updated_at": "2019-12-13T02:05:54.532Z",
    "account_id": 595
  },
  {
    "id": 323,
    "msisdn": "+252662346090",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.530Z",
    "updated_at": "2019-12-13T02:05:54.530Z",
    "account_id": 595
  },
  {
    "id": 322,
    "msisdn": "+252662346089",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.529Z",
    "updated_at": "2019-12-13T02:05:54.529Z",
    "account_id": 595
  },
  {
    "id": 321,
    "msisdn": "+252662346088",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.527Z",
    "updated_at": "2019-12-13T02:05:54.527Z",
    "account_id": 595
  },
  {
    "id": 320,
    "msisdn": "+252662346087",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.525Z",
    "updated_at": "2019-12-13T02:05:54.525Z",
    "account_id": 595
  },
  {
    "id": 319,
    "msisdn": "+252662346086",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.524Z",
    "updated_at": "2019-12-13T02:05:54.524Z",
    "account_id": 595
  },
  {
    "id": 318,
    "msisdn": "+252662346085",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-12-13T02:05:54.522Z",
    "updated_at": "2019-12-13T02:05:54.522Z",
    "account_id": 595
  }
]
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][gender]=f&q[created_at_after]=2019-12-12&sort=-id%2Ccreated_at" -X GET \
    -H "Authorization: Bearer TAIbRP8xouiEC6mUcCWQtDxxQVwLPLSyVUxovky_AX0"

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

Endpoint

PATCH /api/contacts/345

PATCH /api/contacts/:id

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/345
204 No Content
curl "https://scfm.somleng.org/api/contacts/345" -d '{
  "metadata": {
    "name": "Kate"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer BMDX4_6z4Y5_dnt9qAkGYaUsFtLwBtBuazWUu5c1Ix8"

Users

Create a User

Request

Endpoint

POST /api/users

POST /api/users

Parameters

{
  "email": "user32@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/25
201 Created
{
  "id": 25,
  "account_id": 602,
  "metadata": {
    "foo": "bar"
  },
  "email": "user32@example.com",
  "created_at": "2019-12-13T02:05:54.704Z",
  "updated_at": "2019-12-13T02:05:54.704Z",
  "locale": "en"
}
curl "https://scfm.somleng.org/api/users" -d '{
  "email": "user32@example.com",
  "password": "secret123",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer 3CEBTvQIGmS1U9zrBSuePE7aUt7367PRt3ih92QGB80"

Create a User Event

Request

Endpoint

POST /api/users/30/user_events

POST /api/users/:user_id/user_events

Parameters

{
  "event": "invite"
}
Name Description
event required Only invite is supported at this time

Response

Location: /api/users/30
201 Created
{
  "account_id": 608,
  "id": 30,
  "metadata": {
  },
  "email": "user37@example.com",
  "created_at": "2019-12-13T02:05:54.819Z",
  "updated_at": "2019-12-13T02:05:54.835Z",
  "locale": "en"
}
curl "https://scfm.somleng.org/api/users/30/user_events" -d '{
  "event": "invite"
}' -X POST \
    -H "Authorization: Bearer Gc3lanSkbQBwXf3zbpEcUH0AN9DV_RhLW8ZT4vHcKCk"

Delete a User

Request

Endpoint

DELETE /api/users/29

DELETE /api/users/:id

Parameters

None known.

Response

Location: /api/users
204 No Content
curl "https://scfm.somleng.org/api/users/29" -d '' -X DELETE \
    -H "Authorization: Bearer W2F3OpR6jTakpDA21reahK_BItBHO1EV0VQ9ebCnX6Q"

List all Users

Request

Endpoint

GET /api/users?q[metadata][foo]=bar

GET /api/users

Parameters

q: {"metadata"=>{"foo"=>"bar"}}

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 20,
    "account_id": 598,
    "metadata": {
      "foo": "bar"
    },
    "email": "user27@example.com",
    "created_at": "2019-12-13T02:05:54.622Z",
    "updated_at": "2019-12-13T02:05:54.622Z",
    "locale": "en"
  }
]
curl -g "https://scfm.somleng.org/api/users?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer XP6-11b5Dth-_5pOytM2JKDGbZmhjbLNswpF5dddaPQ"

Retrieve a User

Request

Endpoint

GET /api/users/27

GET /api/users/:id

Parameters

None known.

Response

Location: /api/users/27
200 OK
{
  "id": 27,
  "account_id": 605,
  "metadata": {
  },
  "email": "user34@example.com",
  "created_at": "2019-12-13T02:05:54.739Z",
  "updated_at": "2019-12-13T02:05:54.739Z",
  "locale": "en"
}
curl -g "https://scfm.somleng.org/api/users/27" -X GET \
    -H "Authorization: Bearer Z5oWsuU8By12vbLcPeT__T2gMfPrekaQeJUAHOBY6gQ"

Update a User

Request

Endpoint

PATCH /api/users/28

PATCH /api/users/:id

Parameters

{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/users/28
204 No Content
curl "https://scfm.somleng.org/api/users/28" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer 7n2iOpSvQpR1KqXV0WIAxpLt-8t3BMNxcUycO8PhejE"