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": "CiVpKOAKFjOkakwetvV_BpYUH1okqDE8aJHzrbTifU0",
  "created_at": "2019-10-05T06:57:48.297Z",
  "updated_at": "2019-10-05T06:57:48.298Z",
  "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 zmIrypjkr1N7t-rhT3KfUH2wP8MIyquhjcPa2Es-Lbo"

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 1bjpz2Zt59vtUU_co9lDKQcfwDSGSRhrq60kXQrl7M0"

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": "ASlVC7Y2eFDN5Dbd_t9EKObVyrhcHjuvc3Uj1isLXM8",
    "created_at": "2019-10-05T06:57:48.195Z",
    "updated_at": "2019-10-05T06:57:48.197Z",
    "metadata": {
      "foo": "bar"
    },
    "permissions": [

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

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": "VAKNqGV5GKUR18HucGm4oW6Yd3o_q7wk1TJ-msbjyvQ",
  "created_at": "2019-10-05T06:57:48.333Z",
  "updated_at": "2019-10-05T06:57:48.333Z",
  "metadata": {
  },
  "permissions": [
    "access_tokens_read",
    "access_tokens_write"
  ]
}
curl -g "https://scfm.somleng.org/api/access_tokens/19" -X GET \
    -H "Authorization: Bearer VAKNqGV5GKUR18HucGm4oW6Yd3o_q7wk1TJ-msbjyvQ"

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 Sw90hFZQmJvDsq3IUG85Oolwu89h2lH3H_Xo1mepJM0"

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-10-05T06:57:48.450Z",
  "updated_at": "2019-10-05T06:57:48.450Z",
  "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 OEgvi8Os55UxOtKGfo15Akc7IkymvR2OaeUE50EiBv8"

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 xV3apAO8ycytjeh7z4rm0MM-Jfn9B5DL1vXKzy38_Fk"

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-10-05T06:57:48.545Z",
  "updated_at": "2019-10-05T06:57:48.545Z",
  "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 C7hwZeTMlatGzfIrBpy3G1WrIy1kDm514_O1b6f1X80"

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 dbczb8zbyeGdO-S6VsY5Mce-zriEnzlBQMgjYDhA420"

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-10-05T06:57:48.489Z",
    "updated_at": "2019-10-05T06:57:48.489Z",
    "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 jAGlSUyCWTQdHna98C3MgYGe_Xrqe11Po1JtnQUn9b4"

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-10-05T06:57:48.551Z",
  "updated_at": "2019-10-05T06:57:48.551Z",
  "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 cWDdHWM9b4gaMyUObtHjWMlu5EBFoP3DaaD7urwtNCA"

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": "ca861c37-1ae8-4a27-be1a-0f98dc04fe38",
  "twilio_auth_token": "a7ef33ac-6b7c-4adb-a967-98222ee8039b",
  "somleng_auth_token": "0560975b-c195-41ff-ad71-e044c5d30cd0",
  "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": "ca861c37-1ae8-4a27-be1a-0f98dc04fe38",
  "twilio_auth_token": "a7ef33ac-6b7c-4adb-a967-98222ee8039b",
  "somleng_auth_token": "0560975b-c195-41ff-ad71-e044c5d30cd0",
  "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 HACku3asooWZkVTZ_JvXZifI_GvcCzspMAbuee0qbqI"

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/93
201 Created
{
  "id": 93,
  "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-10-05T06:57:48.735Z",
  "updated_at": "2019-10-05T06:57:48.735Z",
  "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 C2_NJfL9H_t_6Uf5GlF2EbvGfkynikgFZRWE_T7B9F8"

Create a Batch Operation Event

Request

Endpoint

POST /api/batch_operations/100/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/100
201 Created
{
  "id": 100,
  "callout_id": 242,
  "parameters": {
  },
  "metadata": {
  },
  "status": "queued",
  "created_at": "2019-10-05T06:57:48.922Z",
  "updated_at": "2019-10-05T06:57:48.922Z",
  "account_id": 516,
  "type": "BatchOperation::CalloutPopulation"
}
curl "https://scfm.somleng.org/api/batch_operations/100/batch_operation_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer se_x3QJBWaHWtfdNHTugN3hPHYJdr5xF8B4_gYs7Qec"

Delete a Batch Operation

Request

Endpoint

DELETE /api/batch_operations/98

DELETE /api/batch_operations/:id

Parameters

None known.

Response

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

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": 89,
    "callout_id": 233,
    "parameters": {
    },
    "metadata": {
      "foo": "bar"
    },
    "status": "preview",
    "created_at": "2019-10-05T06:57:48.655Z",
    "updated_at": "2019-10-05T06:57:48.655Z",
    "account_id": 503,
    "type": "BatchOperation::CalloutPopulation"
  }
]
curl -g "https://scfm.somleng.org/api/batch_operations?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer WR6J-kYuJn-1YyAmh-0MibiuRXCGOlrtQhKN5uQGey0"

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": 236,
  "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/92
201 Created
{
  "id": 92,
  "callout_id": 236,
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2019-10-05T06:57:48.708Z",
  "updated_at": "2019-10-05T06:57:48.708Z",
  "account_id": 505,
  "type": "BatchOperation::CalloutPopulation"
}
curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "callout_id": 236,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}' -X POST \
    -H "Authorization: Bearer xs0xaxzjqpbVDbaQWOERq11jgt86f3nYln97FbppLms"

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/105/preview/contacts

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

Parameters

None known.

Response

Per-Page: 25
Total: 1
200 OK
[
  {
    "id": 220,
    "msisdn": "+252662345960",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-10-05T06:57:49.186Z",
    "updated_at": "2019-10-05T06:57:49.186Z",
    "account_id": 521
  }
]
curl -g "https://scfm.somleng.org/api/batch_operations/105/preview/contacts" -X GET \
    -H "Authorization: Bearer NmSKbgarkGbjtahIjrSFV-N516cvYypdNZQ7fn4CJto"

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/94
201 Created
{
  "id": 94,
  "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-10-05T06:57:48.757Z",
  "updated_at": "2019-10-05T06:57:48.757Z",
  "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 26FI5XqpTf74G0qY9EQwSEoP552DwPjxQmS7l8knl2U"

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/95
201 Created
{
  "id": 95,
  "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-10-05T06:57:48.782Z",
  "updated_at": "2019-10-05T06:57:48.782Z",
  "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 V_GE3cpzaG-f3MKnn227GZRzECAh4qkPu5imq1sS440"

Retrieve a Batch Operation

Request

Endpoint

GET /api/batch_operations/96

GET /api/batch_operations/:id

Parameters

None known.

Response

Location: /api/batch_operations/96
200 OK
{
  "id": 96,
  "callout_id": 237,
  "parameters": {
  },
  "metadata": {
  },
  "status": "preview",
  "created_at": "2019-10-05T06:57:48.816Z",
  "updated_at": "2019-10-05T06:57:48.816Z",
  "account_id": 510,
  "type": "BatchOperation::CalloutPopulation"
}
curl -g "https://scfm.somleng.org/api/batch_operations/96" -X GET \
    -H "Authorization: Bearer BYCJMFQodXdOs8EcHbD3mD_zY9SrBBeUdNX7O7TGMyc"

Update a Batch Operation

Request

Endpoint

PATCH /api/batch_operations/97

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/97
204 No Content
curl "https://scfm.somleng.org/api/batch_operations/97" -d '{
  "metadata": {
    "foo": "bar",
    "bar": "foo"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer r9ROI0Fg57k_8ZuEe0A4LyuSdxxEVCR0K-iBZeVyyMQ"

Callout Participations

Create a Callout Participation

Request

Endpoint

POST /api/callouts/268/callout_participations

POST /api/callouts/:callout_id/callout_participations

Parameters

{
  "contact_id": 241,
  "msisdn": "252662345982",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}

None known.

Response

Location: /api/callout_participations/221
201 Created
{
  "id": 221,
  "callout_id": 268,
  "contact_id": 241,
  "callout_population_id": null,
  "msisdn": "+252662345982",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2019-10-05T06:57:49.614Z",
  "updated_at": "2019-10-05T06:57:49.614Z"
}
curl "https://scfm.somleng.org/api/callouts/268/callout_participations" -d '{
  "contact_id": 241,
  "msisdn": "252662345982",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer yuG6-ZF8YcF98uJaYvhqQqubk8iKXCgfE6Jq73Rnjf8"

Create a Callout Participation with invalid data

Request

Endpoint

POST /api/callouts/269/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/269/callout_participations" -d '' -X POST \
    -H "Authorization: Bearer IAWtBhnwq_WwbzM6PCFV47KaEi9oz7j9EaRtl8oM5T4"

Delete a Callout Participation

Request

Endpoint

DELETE /api/callout_participations/224

DELETE /api/callout_participations/:id

Parameters

None known.

Response

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

Delete a Callout Participation with phone calls

Request

Endpoint

DELETE /api/callout_participations/225

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/225" -d '' -X DELETE \
    -H "Authorization: Bearer GwQ_8Rv7li5LrmXZF7PMOQcjYrbZzxZyJn8WMCrcOo4"

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": 210,
    "callout_id": 256,
    "contact_id": 230,
    "callout_population_id": null,
    "msisdn": "+252662345970",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-10-05T06:57:49.399Z",
    "updated_at": "2019-10-05T06:57:49.399Z"
  }
]
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 rOT5m1rYmW_xtUl86E12wfvNn6VpBF04HYX-aSEhBNQ"

Retrieve a Callout Participation

Request

Endpoint

GET /api/callout_participations/222

GET /api/callout_participations/:id

Parameters

None known.

Response

Location: /api/callout_participations/222
200 OK
{
  "id": 222,
  "callout_id": 270,
  "contact_id": 242,
  "callout_population_id": null,
  "msisdn": "+252662345983",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-10-05T06:57:49.647Z",
  "updated_at": "2019-10-05T06:57:49.647Z"
}
curl -g "https://scfm.somleng.org/api/callout_participations/222" -X GET \
    -H "Authorization: Bearer ohKwyRm1GhzxIYoQdbT-kqnPcZvOEKRRVVZZy4dJQsA"

Update a Callout Participation

Request

Endpoint

PATCH /api/callout_participations/223

PATCH /api/callout_participations/:id

Parameters

{
  "contact_id": 244,
  "msisdn": "252662345986",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/callout_participations/223
204 No Content
curl "https://scfm.somleng.org/api/callout_participations/223" -d '{
  "contact_id": 244,
  "msisdn": "252662345986",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer rci9CMYHlgUSNwEQks2V6YPs6Mu7TMgVU7Zs2AQWxcQ"

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/279
201 Created
{
  "id": 279,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2019-10-05T06:57:49.866Z",
  "updated_at": "2019-10-05T06:57:49.866Z",
  "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 WN1mhjok-K56Bw1SUxnC5y4uiZumz_D-ygWVES1hTNg"

Create a Callout Event

Request

Endpoint

POST /api/callouts/284/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/284
201 Created
{
  "account_id": 547,
  "id": 284,
  "status": "running",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-10-05T06:57:49.971Z",
  "updated_at": "2019-10-05T06:57:49.993Z",
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}
curl "https://scfm.somleng.org/api/callouts/284/callout_events" -d '{
  "event": "start"
}' -X POST \
    -H "Authorization: Bearer wQ2pbbibMe5a9tP3uaZ0vbkYy9FrYZWgz5fes95jb0s"

Delete a Callout

Request

Endpoint

DELETE /api/callouts/282

DELETE /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts
204 No Content
curl "https://scfm.somleng.org/api/callouts/282" -d '' -X DELETE \
    -H "Authorization: Bearer Mr4zAqlNPal43fjm3ss67IlVh7IMh-ThsiqoKiqnPQM"

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": 274,
    "status": "initialized",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-10-05T06:57:49.760Z",
    "updated_at": "2019-10-05T06:57:49.760Z",
    "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 AJGA8pgj2R_FaqsfQDxy4byRddv9FW0GrsfGBfPTxRs"

Retrieve a Callout

Request

Endpoint

GET /api/callouts/280

GET /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts/280
200 OK
{
  "id": 280,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2019-10-05T06:57:49.875Z",
  "updated_at": "2019-10-05T06:57:49.875Z",
  "account_id": 543,
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}
curl -g "https://scfm.somleng.org/api/callouts/280" -X GET \
    -H "Authorization: Bearer iBksDCTJRg4CWuUlIfwcQSUsZMDmiYQfPGeqw6Njd7E"

Update a Callout

Request

Endpoint

PATCH /api/callouts/281

PATCH /api/callouts/:id

Parameters

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

None known.

Response

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

Contacts

Create a Contact

Request

Endpoint

POST /api/contacts

POST /api/contacts

Parameters

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

Response

Location: /api/contacts/258
201 Created
{
  "id": 258,
  "msisdn": "+252662346000",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2019-10-05T06:57:50.184Z",
  "updated_at": "2019-10-05T06:57:50.184Z",
  "account_id": 555
}
curl "https://scfm.somleng.org/api/contacts" -d '{
  "msisdn": "252662346000",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer VHIia_iiyish3ung7VDnc_1QyO_X5U8zC_ghgTzjS7E"

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": "252662346004",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}

None known.

Response

Location: /api/contacts/262
201 Created
{
  "id": 262,
  "msisdn": "+252662346004",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2019-10-05T06:57:50.286Z",
  "updated_at": "2019-10-05T06:57:50.286Z",
  "account_id": 560
}
curl "https://scfm.somleng.org/api/contact_data" -d '{
  "msisdn": "252662346004",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer EjfVexSDCRdvbqHnB1Wjsyy3n2WnfCEaUqQ8rVvO49k"

Delete a Contact

Request

Endpoint

DELETE /api/contacts/264

DELETE /api/contacts/:id

Parameters

None known.

Response

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

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": 249,
    "msisdn": "+252662345991",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2019-10-05T06:57:50.041Z",
    "updated_at": "2019-10-05T06:57:50.041Z",
    "account_id": 550
  }
]
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer w1wsKJEZcq80kh-ZVaLLUQvi-_zZ7-gCGhDQ4AXKZ4Q"

Retrieve a Contact

Request

Endpoint

GET /api/contacts/259

GET /api/contacts/:id

Parameters

None known.

Response

Location: /api/contacts/259
200 OK
{
  "id": 259,
  "msisdn": "+252662346001",
  "metadata": {
  },
  "created_at": "2019-10-05T06:57:50.210Z",
  "updated_at": "2019-10-05T06:57:50.210Z",
  "account_id": 557
}
curl -g "https://scfm.somleng.org/api/contacts/259" -X GET \
    -H "Authorization: Bearer bN8BIk-WvM7k5doYE1iaQJHgDfz89p3SokHRMW0T1gU"

Update a Contact

Request

Endpoint

PATCH /api/contacts/260

PATCH /api/contacts/:id

Parameters

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

None known.

Response

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

Phone Calls

Create a Phone Call

Request

Endpoint

POST /api/callout_participations/248/phone_calls

POST /api/callout_participations/:callout_participation_id/phone_calls

Parameters

{
  "msisdn": "252662346025",
  "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",
    "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/200
201 Created
{
  "id": 200,
  "callout_participation_id": 248,
  "contact_id": 282,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "created",
  "msisdn": "+252662346025",
  "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",
    "application_sid": "application_sid"
  },
  "remote_queue_response": {
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "remotely_queued_at": null,
  "created_at": "2019-10-05T06:57:50.742Z",
  "updated_at": "2019-10-05T06:57:50.742Z",
  "duration": 0,
  "lock_version": 0
}
curl "https://scfm.somleng.org/api/callout_participations/248/phone_calls" -d '{
  "msisdn": "252662346025",
  "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",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer L3ujEIdxeu09MA4fKKLbpL0P2I3eYmo98036aGuhLso"

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/205/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/205
201 Created
{
  "id": 205,
  "callout_participation_id": 254,
  "contact_id": 288,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "queued",
  "msisdn": "+252662346033",
  "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",
    "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-10-05T06:57:50.917Z",
  "updated_at": "2019-10-05T06:57:50.933Z",
  "duration": 0,
  "lock_version": 1
}
curl "https://scfm.somleng.org/api/phone_calls/205/phone_call_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer lFDyflql_7mVsE_uqJaR1-ZhH1Jk2ZMc0i0zpGww76I"

Delete a Phone Call

Request

Endpoint

DELETE /api/phone_calls/203

DELETE /api/phone_calls/:id

Parameters

None known.

Response

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

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": 185,
    "callout_participation_id": 233,
    "contact_id": 267,
    "create_batch_operation_id": null,
    "queue_batch_operation_id": null,
    "queue_remote_fetch_batch_operation_id": null,
    "status": "created",
    "msisdn": "+252662346009",
    "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",
      "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-10-05T06:57:50.379Z",
    "updated_at": "2019-10-05T06:57:50.379Z",
    "duration": 0,
    "lock_version": 0
  }
]
curl -g "https://scfm.somleng.org/api/phone_calls?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer XPX-4gwvYWOkAAbTXk82crrWURKOyJEibXynR5SHA8U"

Retrieve a Phone Call

Request

Endpoint

GET /api/phone_calls/201

GET /api/phone_calls/:id

Parameters

None known.

Response

Location: /api/phone_calls/201
200 OK
{
  "id": 201,
  "callout_participation_id": 250,
  "contact_id": 284,
  "create_batch_operation_id": null,
  "queue_batch_operation_id": null,
  "queue_remote_fetch_batch_operation_id": null,
  "status": "created",
  "msisdn": "+252662346028",
  "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",
    "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-10-05T06:57:50.788Z",
  "updated_at": "2019-10-05T06:57:50.788Z",
  "duration": 0,
  "lock_version": 0
}
curl -g "https://scfm.somleng.org/api/phone_calls/201" -X GET \
    -H "Authorization: Bearer LU7Y0bQV62fTES-ryIDeosTA5OTWX6MFanNrochjcsQ"

Update a Phone Call

Request

Endpoint

PATCH /api/phone_calls/202

PATCH /api/phone_calls/:id

Parameters

{
  "msisdn": "252662346030",
  "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",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/phone_calls/202
204 No Content
curl "https://scfm.somleng.org/api/phone_calls/202" -d '{
  "msisdn": "252662346030",
  "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",
    "application_sid": "application_sid"
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer yMdQE6mI2ocxZ6ABzq400-lHwq-maBURWvUqSnjSvLQ"

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": 24,
    "phone_call_id": 208,
    "details": {
      "To": "345",
      "From": "252662346037",
      "Digits": "5",
      "CallSid": "105006ff-f1b2-4674-8def-96b1164a9f77",
      "Direction": "inbound",
      "AccountSid": "f40a9b1c-da81-492e-92c2-c705aca68be1",
      "ApiVersion": "2010-04-01",
      "CallStatus": "completed"
    },
    "metadata": {
      "foo": "bar"
    },
    "remote_call_id": "105006ff-f1b2-4674-8def-96b1164a9f77",
    "remote_direction": "inbound",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "created_at": "2019-10-05T06:57:51.048Z",
    "updated_at": "2019-10-05T06:57:51.048Z",
    "call_duration": 0
  }
]
curl -g "https://scfm.somleng.org/api/remote_phone_call_events?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer 0p65hijuFfiXB2e26btvS6WyAsIC44dlp8DB0Koz-Hs"

Retrieve a Remote Phone Call Event

Request

Endpoint

GET /api/remote_phone_call_events/35

GET /api/remote_phone_call_events/:id

Parameters

None known.

Response

Location: /api/remote_phone_call_events/35
200 OK
{
  "id": 35,
  "phone_call_id": 219,
  "details": {
    "To": "345",
    "From": "252662346059",
    "Digits": "5",
    "CallSid": "e6ddffee-8192-4db1-9d2e-6c14f5bc7d75",
    "Direction": "inbound",
    "AccountSid": "c074e450-2766-43e4-b604-f5288f270a0c",
    "ApiVersion": "2010-04-01",
    "CallStatus": "completed"
  },
  "metadata": {
  },
  "remote_call_id": "e6ddffee-8192-4db1-9d2e-6c14f5bc7d75",
  "remote_direction": "inbound",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "created_at": "2019-10-05T06:57:51.328Z",
  "updated_at": "2019-10-05T06:57:51.328Z",
  "call_duration": 0
}
curl -g "https://scfm.somleng.org/api/remote_phone_call_events/35" -X GET \
    -H "Authorization: Bearer jPNcnZfsI7Q74qZomOKZn12x_ClSxqmhlZnjjMAFOWw"

Update a Remote Phone Call Event

Request

Endpoint

PATCH /api/remote_phone_call_events/36

PATCH /api/remote_phone_call_events/:id

Parameters

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

None known.

Response

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

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-10-04&sort=-id%2Ccreated_at

GET /api/contacts

Parameters

q: {"metadata"=>{"gender"=>"f"}, "created_at_after"=>"2019-10-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": 332,
    "msisdn": "+252662346088",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.528Z",
    "updated_at": "2019-10-05T06:57:51.528Z",
    "account_id": 595
  },
  {
    "id": 331,
    "msisdn": "+252662346087",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.527Z",
    "updated_at": "2019-10-05T06:57:51.527Z",
    "account_id": 595
  },
  {
    "id": 330,
    "msisdn": "+252662346086",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.525Z",
    "updated_at": "2019-10-05T06:57:51.525Z",
    "account_id": 595
  },
  {
    "id": 329,
    "msisdn": "+252662346085",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.524Z",
    "updated_at": "2019-10-05T06:57:51.524Z",
    "account_id": 595
  },
  {
    "id": 328,
    "msisdn": "+252662346084",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.522Z",
    "updated_at": "2019-10-05T06:57:51.522Z",
    "account_id": 595
  },
  {
    "id": 327,
    "msisdn": "+252662346083",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.521Z",
    "updated_at": "2019-10-05T06:57:51.521Z",
    "account_id": 595
  },
  {
    "id": 326,
    "msisdn": "+252662346082",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.519Z",
    "updated_at": "2019-10-05T06:57:51.519Z",
    "account_id": 595
  },
  {
    "id": 325,
    "msisdn": "+252662346081",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.518Z",
    "updated_at": "2019-10-05T06:57:51.518Z",
    "account_id": 595
  },
  {
    "id": 324,
    "msisdn": "+252662346080",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.516Z",
    "updated_at": "2019-10-05T06:57:51.516Z",
    "account_id": 595
  },
  {
    "id": 323,
    "msisdn": "+252662346079",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.515Z",
    "updated_at": "2019-10-05T06:57:51.515Z",
    "account_id": 595
  },
  {
    "id": 322,
    "msisdn": "+252662346078",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.513Z",
    "updated_at": "2019-10-05T06:57:51.513Z",
    "account_id": 595
  },
  {
    "id": 321,
    "msisdn": "+252662346077",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.512Z",
    "updated_at": "2019-10-05T06:57:51.512Z",
    "account_id": 595
  },
  {
    "id": 320,
    "msisdn": "+252662346076",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.510Z",
    "updated_at": "2019-10-05T06:57:51.510Z",
    "account_id": 595
  },
  {
    "id": 319,
    "msisdn": "+252662346075",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.509Z",
    "updated_at": "2019-10-05T06:57:51.509Z",
    "account_id": 595
  },
  {
    "id": 318,
    "msisdn": "+252662346074",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.507Z",
    "updated_at": "2019-10-05T06:57:51.507Z",
    "account_id": 595
  },
  {
    "id": 317,
    "msisdn": "+252662346073",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.505Z",
    "updated_at": "2019-10-05T06:57:51.505Z",
    "account_id": 595
  },
  {
    "id": 316,
    "msisdn": "+252662346072",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.503Z",
    "updated_at": "2019-10-05T06:57:51.503Z",
    "account_id": 595
  },
  {
    "id": 315,
    "msisdn": "+252662346071",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.501Z",
    "updated_at": "2019-10-05T06:57:51.501Z",
    "account_id": 595
  },
  {
    "id": 314,
    "msisdn": "+252662346070",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.500Z",
    "updated_at": "2019-10-05T06:57:51.500Z",
    "account_id": 595
  },
  {
    "id": 313,
    "msisdn": "+252662346069",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.497Z",
    "updated_at": "2019-10-05T06:57:51.497Z",
    "account_id": 595
  },
  {
    "id": 312,
    "msisdn": "+252662346068",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.495Z",
    "updated_at": "2019-10-05T06:57:51.495Z",
    "account_id": 595
  },
  {
    "id": 311,
    "msisdn": "+252662346067",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.493Z",
    "updated_at": "2019-10-05T06:57:51.493Z",
    "account_id": 595
  },
  {
    "id": 310,
    "msisdn": "+252662346066",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.491Z",
    "updated_at": "2019-10-05T06:57:51.491Z",
    "account_id": 595
  },
  {
    "id": 309,
    "msisdn": "+252662346065",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.489Z",
    "updated_at": "2019-10-05T06:57:51.489Z",
    "account_id": 595
  },
  {
    "id": 308,
    "msisdn": "+252662346064",
    "metadata": {
      "gender": "f"
    },
    "created_at": "2019-10-05T06:57:51.487Z",
    "updated_at": "2019-10-05T06:57:51.487Z",
    "account_id": 595
  }
]
curl -g "https://scfm.somleng.org/api/contacts?q[metadata][gender]=f&q[created_at_after]=2019-10-04&sort=-id%2Ccreated_at" -X GET \
    -H "Authorization: Bearer vmjANaddyYdm1-a3SSIGVTwel2CHFu0hxjLAlulE4Io"

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/335

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

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-10-05T06:57:51.658Z",
  "updated_at": "2019-10-05T06:57:51.658Z",
  "locale": "en"
}
curl "https://scfm.somleng.org/api/users" -d '{
  "email": "user32@example.com",
  "password": "secret123",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer 7ZmyIQBFQWsGLNeEluWdO4-L449gs_ZtAgpDuZCd2i8"

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-10-05T06:57:51.805Z",
  "updated_at": "2019-10-05T06:57:51.820Z",
  "locale": "en"
}
curl "https://scfm.somleng.org/api/users/30/user_events" -d '{
  "event": "invite"
}' -X POST \
    -H "Authorization: Bearer gQQRf6tqksULTN1tdS8Mp7hpXbzSmwX4ULe9M814xBo"

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 PBs3K1uVDh_EiHgyaR_UTiYmdChO6latGE_dSkIfPv8"

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-10-05T06:57:51.583Z",
    "updated_at": "2019-10-05T06:57:51.583Z",
    "locale": "en"
  }
]
curl -g "https://scfm.somleng.org/api/users?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer FsD-vtWaQFUENaqqelaiHMdQAJTeImi3eQ5SUN2Sk8M"

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-10-05T06:57:51.725Z",
  "updated_at": "2019-10-05T06:57:51.725Z",
  "locale": "en"
}
curl -g "https://scfm.somleng.org/api/users/27" -X GET \
    -H "Authorization: Bearer 7SBnywuVf1wLHHgCvUBvZ1V_-dOohgdtcIJ3dajiikA"

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 OjWE9dtFCFZ0slDQuYaocZnsu8dLW86DsVDIzD6lPOk"