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

[binary data]

curl "https://scfm.somleng.org/api/access_tokens" -d '{
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}' -X POST \
    -H "Authorization: Bearer welgBElCUqeiMHOBxsuiySKB_oeA37e2lDitwPVDDiw"

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 BO9KksWH_JbjLxYZrQg0y-wRFL0ig_BQ3hvupG6lVW8"

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

[binary data]

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

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

[binary data]

curl -g "https://scfm.somleng.org/api/access_tokens/19" -X GET \
    -H "Authorization: Bearer WlmOZjnC5igPZMMHkoLNPSeMZKBTSbM2z68erAR4u6E"

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 -QKbecM1hzAmJ8J8PFwLtHV8Li-DQw-LL5ab0nUDZ2k"

Account Details

Retrieve Account Details

Request

Endpoint

GET /api/account

GET /api/account

Parameters

None known.

Response

Location: /api/accounts/492
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/account" -X GET \
    -H "Authorization: Bearer CfblGF6XQ1I73n8NEuNXPk-xbLzlBDblXWqa9DffuR4"

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/493
204 No Content

curl "https://scfm.somleng.org/api/account" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer snB7_XPx5kPcss8qfC5kvvFc4yV2PWRi2oXnXxxW6dU"

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/498
201 Created

[binary data]

curl "https://scfm.somleng.org/api/accounts" -d '' -X POST \
    -H "Authorization: Bearer g0VMGZ7iamAMwW6NciBDXot-quIQGZtSOKukMebD448"

Delete an Account

Request

Endpoint

DELETE /api/accounts/503

DELETE /api/accounts/:id

Parameters

None known.

Response

Location: /api/accounts
204 No Content

curl "https://scfm.somleng.org/api/accounts/503" -d '' -X DELETE \
    -H "Authorization: Bearer 7iA--vJDlY6-CHaYMXInj_-Mgdv-UPbqG4jCvyQTdMk"

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

[binary data]

curl -g "https://scfm.somleng.org/api/accounts?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer 3iHVr7rKfSvC-C6mLhXBQK63Bb6j4b9H39pIxHAlkUs"

Retrieve an Account

Request

Endpoint

GET /api/accounts/499

GET /api/accounts/:id

Parameters

None known.

Response

Location: /api/accounts/499
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/accounts/499" -X GET \
    -H "Authorization: Bearer k4ldKIJkIkrl_kQqBGUWK-M9E28ap5_kR9GD7XkVJoQ"

Update an Account

Request

Endpoint

PATCH /api/accounts/501

PATCH /api/accounts/:id

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "ac78f872-45db-4568-9fe2-057e733817db",
  "twilio_auth_token": "68a80e80-7551-45ee-9b92-abfbed44c7f3",
  "somleng_auth_token": "618de17f-870e-438d-87d5-e8d66aea5f15",
  "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/501
204 No Content

curl "https://scfm.somleng.org/api/accounts/501" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "ac78f872-45db-4568-9fe2-057e733817db",
  "twilio_auth_token": "68a80e80-7551-45ee-9b92-abfbed44c7f3",
  "somleng_auth_token": "618de17f-870e-438d-87d5-e8d66aea5f15",
  "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 4Ngi4YBRfMpx8PxIV2ztBjtFJ85hS64t_fPaJYbZGDg"

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/72
201 Created

[binary data]

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

Create a Batch Operation Event

Request

Endpoint

POST /api/batch_operations/79/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/79
201 Created

[binary data]

curl "https://scfm.somleng.org/api/batch_operations/79/batch_operation_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer rnjfTVDskYYcLHQvYvbR6UiH0XoILnu2d-V8qFMhrFo"

Delete a Batch Operation

Request

Endpoint

DELETE /api/batch_operations/77

DELETE /api/batch_operations/:id

Parameters

None known.

Response

Location: /api/batch_operations
204 No Content

curl "https://scfm.somleng.org/api/batch_operations/77" -d '' -X DELETE \
    -H "Authorization: Bearer KxJWdntjm26MDJzm1ETBmLq49INJ9rRiLObTQYZW-U8"

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

[binary data]

curl -g "https://scfm.somleng.org/api/batch_operations?q[metadata][foo]=bar" -X GET \
    -H "Authorization: Bearer 45CjEuhydPn_6F4MlBJ8I-fKNcpfEvDGVs5WpNs1XSc"

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": 243,
  "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/71
201 Created

[binary data]

curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "callout_id": 243,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "contact_filter_params": {
      "metadata": {
        "gender": "f"
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}' -X POST \
    -H "Authorization: Bearer dnJ5YT3srSyQOb3c5Zt3HDX-8DRx0NQ5tD-wyuBlP8g"

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

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

Parameters

None known.

Response

Per-Page: 25
Total: 1
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/batch_operations/84/preview/contacts" -X GET \
    -H "Authorization: Bearer Vpt-8KJwBlW-UaNgbqrxMIv7ta45D4fFIzA99wPAodg"

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/73
201 Created

[binary data]

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 qIqYRG3XnqxU4-WYVJDHo13nmEr3KjuHD6feF1PbPa0"

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/74
201 Created

[binary data]

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

Retrieve a Batch Operation

Request

Endpoint

GET /api/batch_operations/75

GET /api/batch_operations/:id

Parameters

None known.

Response

Location: /api/batch_operations/75
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/batch_operations/75" -X GET \
    -H "Authorization: Bearer TZQV269QXneo7y7iqnhiIILTqvKrtz_wW-T4qSRPAyY"

Update a Batch Operation

Request

Endpoint

PATCH /api/batch_operations/76

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/76
204 No Content

curl "https://scfm.somleng.org/api/batch_operations/76" -d '{
  "metadata": {
    "foo": "bar",
    "bar": "foo"
  },
  "parameters": {
    "skip_validate_preview_presence": "1",
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer sTRWV6jsSK-Bkok7Eim32pfmbXQqnsQwAtwmHgdn-h4"

Callout Participations

Create a Callout Participation

Request

Endpoint

POST /api/callouts/275/callout_participations

POST /api/callouts/:callout_id/callout_participations

Parameters

{
  "contact_id": 250,
  "msisdn": "252662346005",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}

None known.

Response

Location: /api/callout_participations/229
201 Created

[binary data]

curl "https://scfm.somleng.org/api/callouts/275/callout_participations" -d '{
  "contact_id": 250,
  "msisdn": "252662346005",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer pNDOX49w4AcYTFY8ujqwYwf-LcK9O4Xh_yuQKgrfZRU"

Create a Callout Participation with invalid data

Request

Endpoint

POST /api/callouts/276/callout_participations

POST /api/callouts/:callout_id/callout_participations

Parameters

None known.

Response


422 Unprocessable Entity

[binary data]

curl "https://scfm.somleng.org/api/callouts/276/callout_participations" -d '' -X POST \
    -H "Authorization: Bearer 7qHvijD7J0j2vxpK0CI5tw53ZGtRLrEK878yK78dRyc"

Delete a Callout Participation

Request

Endpoint

DELETE /api/callout_participations/232

DELETE /api/callout_participations/:id

Parameters

None known.

Response

Location: /api/callout_participations
204 No Content

curl "https://scfm.somleng.org/api/callout_participations/232" -d '' -X DELETE \
    -H "Authorization: Bearer HGqD6auWyHo2zZpJPN8eMmP305m0aYROgULa1KxMpyA"

Delete a Callout Participation with phone calls

Request

Endpoint

DELETE /api/callout_participations/233

DELETE /api/callout_participations/:id

Parameters

None known.

Response


422 Unprocessable Entity

[binary data]

curl "https://scfm.somleng.org/api/callout_participations/233" -d '' -X DELETE \
    -H "Authorization: Bearer wfY66Of-yvei0XOSdnvvD566mzymrV18m6tZLjVJJJg"

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

[binary data]

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

Retrieve a Callout Participation

Request

Endpoint

GET /api/callout_participations/230

GET /api/callout_participations/:id

Parameters

None known.

Response

Location: /api/callout_participations/230
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/callout_participations/230" -X GET \
    -H "Authorization: Bearer _t9NIEv5X12SwkhFcL6opJPF1h8d5tKVezLp32PLSXE"

Update a Callout Participation

Request

Endpoint

PATCH /api/callout_participations/231

PATCH /api/callout_participations/:id

Parameters

{
  "contact_id": 253,
  "msisdn": "252662346009",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/callout_participations/231
204 No Content

curl "https://scfm.somleng.org/api/callout_participations/231" -d '{
  "contact_id": 253,
  "msisdn": "252662346009",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer pRsq_ByuQQ77T7Oz1LLI7dOBSIO8RbglalNMSxphsUM"

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/286
201 Created

[binary data]

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

Create a Callout Event

Request

Endpoint

POST /api/callouts/291/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/291
201 Created

[binary data]

curl "https://scfm.somleng.org/api/callouts/291/callout_events" -d '{
  "event": "start"
}' -X POST \
    -H "Authorization: Bearer EAnszhPlvoLySlJe3iH4_G4qkPk2qDJZGdlhyvM3an8"

Delete a Callout

Request

Endpoint

DELETE /api/callouts/289

DELETE /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts
204 No Content

curl "https://scfm.somleng.org/api/callouts/289" -d '' -X DELETE \
    -H "Authorization: Bearer InfNEBR7PdtbDY49nP-M5RNwYx5vLQhOlethIYCBWxU"

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

[binary data]

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

Retrieve a Callout

Request

Endpoint

GET /api/callouts/287

GET /api/callouts/:id

Parameters

None known.

Response

Location: /api/callouts/287
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/callouts/287" -X GET \
    -H "Authorization: Bearer nmxTUSiITrvdLhuNzoIYopiZ1UDXfUP817UxdRveaEY"

Update a Callout

Request

Endpoint

PATCH /api/callouts/288

PATCH /api/callouts/:id

Parameters

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

None known.

Response

Location: /api/callouts/288
204 No Content

curl "https://scfm.somleng.org/api/callouts/288" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer 2PDAUXuGUr0rXeHQdaC2Aka8xY0DtOuw2g19F-xHXTQ"

Contacts

Create a Contact

Request

Endpoint

POST /api/contacts

POST /api/contacts

Parameters

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

Response

Location: /api/contacts/267
201 Created

[binary data]

curl "https://scfm.somleng.org/api/contacts" -d '{
  "msisdn": "252662346023",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer ZZqMFoclLHiXv_inRXOdZzNcX1axfVVX2udYEV-O5Pg"

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

None known.

Response

Location: /api/contacts/271
201 Created

[binary data]

curl "https://scfm.somleng.org/api/contact_data" -d '{
  "msisdn": "252662346027",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Authorization: Bearer x5638OshA9a2jHBMNa4aBIjNI9GQBnmJlC_n6O2qOZk"

Delete a Contact

Request

Endpoint

DELETE /api/contacts/273

DELETE /api/contacts/:id

Parameters

None known.

Response

Location: /api/contacts
204 No Content

curl "https://scfm.somleng.org/api/contacts/273" -d '' -X DELETE \
    -H "Authorization: Bearer HMh_L_wiFsdxWKLoZ1kOqDqGWoQ6xfZ2m44cbKBHpzw"

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

[binary data]

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

Retrieve a Contact

Request

Endpoint

GET /api/contacts/268

GET /api/contacts/:id

Parameters

None known.

Response

Location: /api/contacts/268
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/contacts/268" -X GET \
    -H "Authorization: Bearer qOFRcm0Bl6lzwHB6H9I4F_cBe-JbAJLvX6JFlaUaLVc"

Update a Contact

Request

Endpoint

PATCH /api/contacts/269

PATCH /api/contacts/:id

Parameters

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

None known.

Response

Location: /api/contacts/269
204 No Content

curl "https://scfm.somleng.org/api/contacts/269" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer xDt6S_WybHgPn7q_cr2mSWlAJA4w-8N7j9dhpbuaZxg"

Phone Calls

Create a Phone Call

Request

Endpoint

POST /api/callout_participations/256/phone_calls

POST /api/callout_participations/:callout_participation_id/phone_calls

Parameters

{
  "msisdn": "252662346048",
  "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/209
201 Created

[binary data]

curl "https://scfm.somleng.org/api/callout_participations/256/phone_calls" -d '{
  "msisdn": "252662346048",
  "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 UfoLQpwUoK4zlH2CfCZ2RwwPgvJS1a_q3jZHYYIBB6o"

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/214/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/214
201 Created

[binary data]

curl "https://scfm.somleng.org/api/phone_calls/214/phone_call_events" -d '{
  "event": "queue"
}' -X POST \
    -H "Authorization: Bearer ffek60-t8oyniAHWj2HR7oVRxaE3jIBIzkzi7FyeoFE"

Delete a Phone Call

Request

Endpoint

DELETE /api/phone_calls/212

DELETE /api/phone_calls/:id

Parameters

None known.

Response

Location: /api/phone_calls
204 No Content

curl "https://scfm.somleng.org/api/phone_calls/212" -d '' -X DELETE \
    -H "Authorization: Bearer Pg1jLJlb3GF5OoLbIeKjX974psyQxN0BJhWrvVZX7Uo"

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

[binary data]

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

Retrieve a Phone Call

Request

Endpoint

GET /api/phone_calls/210

GET /api/phone_calls/:id

Parameters

None known.

Response

Location: /api/phone_calls/210
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/phone_calls/210" -X GET \
    -H "Authorization: Bearer OX-r9fVZbS12nDpFjNAvlRfwBOBbyTCoW-4LVrUyf7Q"

Update a Phone Call

Request

Endpoint

PATCH /api/phone_calls/211

PATCH /api/phone_calls/:id

Parameters

{
  "msisdn": "252662346053",
  "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/211
204 No Content

curl "https://scfm.somleng.org/api/phone_calls/211" -d '{
  "msisdn": "252662346053",
  "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 ZiuDrioiGcEe8Wlr3kTbFpXRkxKRgasHuBQKWvaeiYo"

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

[binary data]

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

Retrieve a Remote Phone Call Event

Request

Endpoint

GET /api/remote_phone_call_events/48

GET /api/remote_phone_call_events/:id

Parameters

None known.

Response

Location: /api/remote_phone_call_events/48
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/remote_phone_call_events/48" -X GET \
    -H "Authorization: Bearer yivkxKwcrnS4sY1vp8u0LLaO99i-MjlAUaQHr1b_hxQ"

Update a Remote Phone Call Event

Request

Endpoint

PATCH /api/remote_phone_call_events/49

PATCH /api/remote_phone_call_events/:id

Parameters

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

None known.

Response

Location: /api/remote_phone_call_events/49
204 No Content

curl "https://scfm.somleng.org/api/remote_phone_call_events/49" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer CtirRzPGn55vbQldDQ-nW5zTm1ZCi9s3BANGQ4RSuM0"

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]=2020-02-07&sort=-id%2Ccreated_at

GET /api/contacts

Parameters

q: {"metadata"=>{"gender"=>"f"}, "created_at_after"=>"2020-02-07"}
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

[binary data]

curl -g "https://scfm.somleng.org/api/contacts?q[metadata][gender]=f&q[created_at_after]=2020-02-07&sort=-id%2Ccreated_at" -X GET \
    -H "Authorization: Bearer mEmXwQyb3b9GOM11qqN1OHInjphRZM7_WGy3seVOcY8"

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

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/344
204 No Content

curl "https://scfm.somleng.org/api/contacts/344" -d '{
  "metadata": {
    "name": "Kate"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer 1wmPjrjVXb44xzjTkdcbehZP7iXUJNW6a_8WR2LLeAA"

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

[binary data]

curl "https://scfm.somleng.org/api/users" -d '{
  "email": "user32@example.com",
  "password": "secret123",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer LCaELinOqX0WVw6NQ1ImDbcV3KTBk8-mUPBuhDVrWYg"

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

[binary data]

curl "https://scfm.somleng.org/api/users/30/user_events" -d '{
  "event": "invite"
}' -X POST \
    -H "Authorization: Bearer yVa6rFdT2H3T0VOUbL-B6yKZ2pUi1fkGNnA8En_PtaY"

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 kq13MIfY-2raotpD8Pd-8g51XuGuJ1q_jIx0gbfFRgM"

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

[binary data]

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

Retrieve a User

Request

Endpoint

GET /api/users/27

GET /api/users/:id

Parameters

None known.

Response

Location: /api/users/27
200 OK

[binary data]

curl -g "https://scfm.somleng.org/api/users/27" -X GET \
    -H "Authorization: Bearer Apq9jnPBmPxnLkyz9Z1Y_AnwGqmkxJctAkPAFUypf_A"

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 ZYi48L74DagxV1Evu1uGJvqBIiNaWTSqgk715yPGI5w"
JSON cURL