NAV
cURL

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

Access Tokens

Create an Access Token

Request

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

Endpoint

POST /api/access_tokens

POST /api/access_tokens

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}
Name Description
permissions An array of permissions for the access token. Valid permissions are: access_tokens_read, access_tokens_write, accounts_read, accounts_write, batch_operations_read, batch_operations_write, callout_participations_read, callout_participations_write, callouts_read, callouts_write, contacts_read, contacts_write, phone_calls_read, phone_calls_write, remote_phone_call_events_read, remote_phone_call_events_write, users_read, users_write, recordings_read

Response

location: /api/access_tokens/16
201 Created

{
  "id": 16,
  "token": "RMo7rWMBse4KvX6XCYmESYuLMG0in97AVud7QuttpNc",
  "created_at": "2024-11-20T11:03:55.077Z",
  "updated_at": "2024-11-20T11:03:55.078Z",
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}

Delete an Access Token

Request

curl "https://scfm.somleng.org/api/access_tokens/21" -d '' -X DELETE \
    -H "Authorization: Bearer 4A02dxZzczgt9iewu5xv-bnGsyk6006Y_c_ue67s4DY"

Endpoint

DELETE /api/access_tokens/:id

DELETE /api/access_tokens/21

Parameters

None known.

Response

location: /api/access_tokens
204 No Content

List all Access Tokens

Request

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

Endpoint

GET /api/access_tokens

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

Parameters

q: {"metadata"=>{"foo"=>"bar"}}
Name Description
q A filter in which to filter resources

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 11,
    "token": "uJaruF3tROTFXdRsHx2po5oCgi9WL_BDGstUygxXCYU",
    "created_at": "2024-11-20T11:03:55.014Z",
    "updated_at": "2024-11-20T11:03:55.015Z",
    "metadata": {
      "foo": "bar"
    },
    "permissions": [

    ]
  }
]

Retrieve an Access Token

Request

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

Endpoint

GET /api/access_tokens/:id

GET /api/access_tokens/19

Parameters

None known.

Response

location: /api/access_tokens/19
200 OK

{
  "id": 19,
  "token": "TXGlsTUbYT6_D8JX7V0qRW9RV9irRRHNwGByjcyVcZI",
  "created_at": "2024-11-20T11:03:55.112Z",
  "updated_at": "2024-11-20T11:03:55.113Z",
  "metadata": {
  },
  "permissions": [
    "access_tokens_read",
    "access_tokens_write"
  ]
}

Update an Access Token

Request

curl "https://scfm.somleng.orgapi/access_tokens/20" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer q5sbT9Y2S6AqzIwThN2ONvAFxk_tHuzp4gxHu9syr4I"

Endpoint

PATCH api/access_tokens/:id

PATCH api/access_tokens/20

Parameters

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

None known.

Response

location: /api/access_tokens/20
204 No Content

Account Details

Retrieve Account Details

Request

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

Endpoint

GET /api/account

GET /api/account

Parameters

None known.

Response

location: /api/accounts/399
200 OK

{
  "id": 399,
  "metadata": {
  },
  "settings": {
    "from_phone_number": "1234",
    "phone_call_queue_limit": 200,
    "max_phone_calls_for_callout_participation": 3
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2024-11-20T11:03:55.170Z",
  "updated_at": "2024-11-20T11:03:55.170Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}

Update Account Details

Request

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

Endpoint

PATCH /api/account

PATCH /api/account

Parameters

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

None known.

Response

location: /api/accounts/400
204 No Content

Accounts

Only super admins can manage accounts.

Create an Account

Request

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

Endpoint

POST /api/accounts

POST /api/accounts

Parameters

None known.

Response

location: /api/accounts/405
201 Created

{
  "id": 405,
  "metadata": {
  },
  "settings": {
    "from_phone_number": "1234",
    "phone_call_queue_limit": 200,
    "max_phone_calls_for_callout_participation": 3
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2024-11-20T11:03:55.230Z",
  "updated_at": "2024-11-20T11:03:55.230Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}

Delete an Account

Request

curl "https://scfm.somleng.org/api/accounts/410" -d '' -X DELETE \
    -H "Authorization: Bearer vsnoHgB7-pB-QSf3_1gNZx0UxtI2sd-FpTtEgZS6KbM"

Endpoint

DELETE /api/accounts/:id

DELETE /api/accounts/410

Parameters

None known.

Response

location: /api/accounts
204 No Content

List all Accounts

Request

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

Endpoint

GET /api/accounts

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 401,
    "metadata": {
      "foo": "bar"
    },
    "settings": {
      "from_phone_number": "1234",
      "phone_call_queue_limit": 200,
      "max_phone_calls_for_callout_participation": 3
    },
    "twilio_account_sid": null,
    "somleng_account_sid": null,
    "twilio_auth_token": null,
    "somleng_auth_token": null,
    "permissions": [

    ],
    "created_at": "2024-11-20T11:03:55.195Z",
    "updated_at": "2024-11-20T11:03:55.195Z",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "platform_provider_name": null,
    "somleng_api_host": null,
    "somleng_api_base_url": null
  }
]

Retrieve an Account

Request

curl -g "https://scfm.somleng.org/api/accounts/406" -X GET \
    -H "Authorization: Bearer XSQYtxKXhJo3OfaL1KwRzKWuxbpmLN6UKvdVJni6Q2Y"

Endpoint

GET /api/accounts/:id

GET /api/accounts/406

Parameters

None known.

Response

location: /api/accounts/406
200 OK

{
  "id": 406,
  "metadata": {
  },
  "settings": {
    "from_phone_number": "1234",
    "phone_call_queue_limit": 200,
    "max_phone_calls_for_callout_participation": 3
  },
  "twilio_account_sid": null,
  "somleng_account_sid": null,
  "twilio_auth_token": null,
  "somleng_auth_token": null,
  "permissions": [

  ],
  "created_at": "2024-11-20T11:03:55.235Z",
  "updated_at": "2024-11-20T11:03:55.235Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null
}

Update an Account

Request

curl "https://scfm.somleng.org/api/accounts/408" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "98c17bfe-8a1c-464d-96c7-bf49b4cf1297",
  "twilio_auth_token": "9b972f7e-e971-45bf-be1f-b49b8d503308",
  "somleng_auth_token": "c661cd90-8a14-4dcb-8b62-9e15b4342516",
  "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 VdiU7PKUIy6AngtCLmO5sYbmzd_4UiV39y3KKbZOQxA"

Endpoint

PATCH /api/accounts/:id

PATCH /api/accounts/408

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "98c17bfe-8a1c-464d-96c7-bf49b4cf1297",
  "twilio_auth_token": "9b972f7e-e971-45bf-be1f-b49b8d503308",
  "somleng_auth_token": "c661cd90-8a14-4dcb-8b62-9e15b4342516",
  "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/408
204 No Content

Batch Operations

Create a Batch Operation Event

Request

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

Endpoint

POST /api/batch_operations/:batch_operation_id/batch_operation_events

POST /api/batch_operations/28/batch_operation_events

Parameters

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

Response

location: /api/batch_operations/28
201 Created

{
  "id": 28,
  "callout_id": 193,
  "parameters": {
  },
  "metadata": {
  },
  "status": "queued",
  "created_at": "2024-11-20T11:03:55.488Z",
  "updated_at": "2024-11-20T11:03:55.488Z",
  "account_id": 425,
  "type": "BatchOperation::CalloutPopulation"
}

Delete a Batch Operation

Request

curl "https://scfm.somleng.org/api/batch_operations/26" -d '' -X DELETE \
    -H "Authorization: Bearer Z-DG0JoDQ6lbw5uSJqLNxBnWiXdEHMbe7IV5EI7ZO4Q"

Endpoint

DELETE /api/batch_operations/:id

DELETE /api/batch_operations/26

Parameters

None known.

Response

location: /api/batch_operations
204 No Content

List all Batch Operations

Request

curl -g "https://scfm.somleng.org/api/batch_operations?q[callout_id]=183" -X GET \
    -H "Authorization: Bearer Oq-lWd0ogz5U1Bct48dS5RR0S4nv2RqLcj0hvJzqhho"

Endpoint

GET /api/batch_operations

GET /api/batch_operations?q[callout_id]=183

Parameters

q: {"callout_id"=>"183"}

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 20,
    "callout_id": 183,
    "parameters": {
    },
    "metadata": {
    },
    "status": "preview",
    "created_at": "2024-11-20T11:03:55.319Z",
    "updated_at": "2024-11-20T11:03:55.319Z",
    "account_id": 414,
    "type": "BatchOperation::CalloutPopulation"
  }
]

Populate a Callout

Creates a batch operation for populating a callout with callout participations. Specify contact_filter_params in order to filter which contacts will participate in the callout.

Request

curl "https://scfm.somleng.org/api/batch_operations" -d '{
  "callout_id": 186,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "contact_filter_params": {
      "metadata": {
        "gender": "f",
        "date_of_birth.date.gteq": "2022-01-01",
        "date_of_birth.date.lt": "2022-02-01",
        "deregistered_at.exists": false
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}' -X POST \
    -H "Authorization: Bearer nzhzB8FZVawRgiyW2s5lEcWP1BulnaCGF_M8UDwZ6oQ"

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "callout_id": 186,
  "metadata": {
    "foo": "bar"
  },
  "parameters": {
    "contact_filter_params": {
      "metadata": {
        "gender": "f",
        "date_of_birth.date.gteq": "2022-01-01",
        "date_of_birth.date.lt": "2022-02-01",
        "deregistered_at.exists": false
      }
    }
  },
  "type": "BatchOperation::CalloutPopulation"
}
Name Description
type required Must be: BatchOperation::CalloutPopulation
parameters Parameters for the batch operation.

contact_filter_params filter the contacts by the specified params. | | callout_id | The id of the callout. |

Response

location: /api/batch_operations/23
201 Created

{
  "id": 23,
  "callout_id": 186,
  "parameters": {
    "contact_filter_params": {
      "metadata": {
        "gender": "f",
        "date_of_birth.date.gteq": "2022-01-01",
        "date_of_birth.date.lt": "2022-02-01",
        "deregistered_at.exists": false
      }
    }
  },
  "metadata": {
    "foo": "bar"
  },
  "status": "preview",
  "created_at": "2024-11-20T11:03:55.354Z",
  "updated_at": "2024-11-20T11:03:55.354Z",
  "account_id": 416,
  "type": "BatchOperation::CalloutPopulation"
}

Retrieve a Batch Operation

Request

curl -g "https://scfm.somleng.org/api/batch_operations/24" -X GET \
    -H "Authorization: Bearer GnHKmZ6p-GhnN3Wo7lQsdT1AFnrAKkK4M0e6R8Sri3o"

Endpoint

GET /api/batch_operations/:id

GET /api/batch_operations/24

Parameters

None known.

Response

location: /api/batch_operations/24
200 OK

{
  "id": 24,
  "callout_id": 188,
  "parameters": {
  },
  "metadata": {
  },
  "status": "preview",
  "created_at": "2024-11-20T11:03:55.401Z",
  "updated_at": "2024-11-20T11:03:55.401Z",
  "account_id": 419,
  "type": "BatchOperation::CalloutPopulation"
}

Update a Batch Operation

Request

curl "https://scfm.somleng.org/api/batch_operations/25" -d '{
  "metadata": {
    "foo": "bar",
    "bar": "foo"
  },
  "parameters": {
    "contact_filter_params": {
      "metadata": {
        "foo": "bar"
      }
    }
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer awIdUeIITwSYxqNHdz1P6mAWQz3PdtPJeWAZO5NAzio"

Endpoint

PATCH /api/batch_operations/:id

PATCH /api/batch_operations/25

Parameters

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

None known.

Response

location: /api/batch_operations/25
204 No Content

Callout Participations

Create a Callout Participation

Request

curl "https://scfm.somleng.org/api/callouts/202/callout_participations" -d '{
  "contact_id": 207,
  "msisdn": "252662345997",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Authorization: Bearer WSCxP7KTpwMoJl46n7WKsyv7jPYuSC_WvY7SiZaTVu0"

Endpoint

POST /api/callouts/:callout_id/callout_participations

POST /api/callouts/202/callout_participations

Parameters

{
  "contact_id": 207,
  "msisdn": "252662345997",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}

None known.

Response

location: /api/callout_participations/166
201 Created

{
  "id": 166,
  "callout_id": 202,
  "contact_id": 207,
  "callout_population_id": null,
  "msisdn": "+252662345997",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2024-11-20T11:03:55.638Z",
  "updated_at": "2024-11-20T11:03:55.638Z",
  "answered": false,
  "phone_calls_count": 0
}

Create a Callout Participation with invalid data

Request

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

Endpoint

POST /api/callouts/:callout_id/callout_participations

POST /api/callouts/203/callout_participations

Parameters

None known.

Response


422 Unprocessable Content

{
  "errors": {
    "msisdn": [
      "can't be blank"
    ],
    "contact": [
      "must exist"
    ]
  }
}

Delete a Callout Participation

Request

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

Endpoint

DELETE /api/callout_participations/:id

DELETE /api/callout_participations/169

Parameters

None known.

Response

location: /api/callout_participations
204 No Content

Delete a Callout Participation with phone calls

Request

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

Endpoint

DELETE /api/callout_participations/:id

DELETE /api/callout_participations/170

Parameters

None known.

Response


422 Unprocessable Content

{
  "errors": {
    "base": [
      "Cannot delete record because dependent phone calls exist"
    ]
  }
}

List all Callout Participations

Request

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

Endpoint

GET /api/callout_participations

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 159,
    "callout_id": 195,
    "contact_id": 200,
    "callout_population_id": null,
    "msisdn": "+252662345989",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2024-11-20T11:03:55.537Z",
    "updated_at": "2024-11-20T11:03:55.537Z",
    "answered": false,
    "phone_calls_count": 0
  }
]

Retrieve a Callout Participation

Request

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

Endpoint

GET /api/callout_participations/:id

GET /api/callout_participations/167

Parameters

None known.

Response

location: /api/callout_participations/167
200 OK

{
  "id": 167,
  "callout_id": 204,
  "contact_id": 208,
  "callout_population_id": null,
  "msisdn": "+252662345998",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2024-11-20T11:03:55.688Z",
  "updated_at": "2024-11-20T11:03:55.688Z",
  "answered": false,
  "phone_calls_count": 0
}

Update a Callout Participation

Request

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

Endpoint

PATCH /api/callout_participations/:id

PATCH /api/callout_participations/168

Parameters

{
  "contact_id": 210,
  "msisdn": "252662346001",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

location: /api/callout_participations/168
204 No Content

Callouts

Create a Callout

Request

curl "https://scfm.somleng.org/api/callouts" -d '{
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "audio_url": "https://www.example.com/sample.mp3",
  "metadata": {
    "foo": "bar"
  },
  "settings": {
    "external_service_1": {
      "foo": "bar"
    }
  }
}' -X POST \
    -H "Authorization: Bearer 3uVFOcwFnscGxwOE2FZuHlNkPp5mUEjQo7E4XqjOMec"

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

{
  "id": 213,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2024-11-20T11:03:55.855Z",
  "updated_at": "2024-11-20T11:03:55.855Z",
  "account_id": 441,
  "audio_url": "https://www.example.com/sample.mp3",
  "settings": {
    "external_service_1": {
      "foo": "bar"
    }
  },
  "created_by_id": null
}

Create a Callout Event

Request

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

Endpoint

POST /api/callouts/:callout_id/callout_events

POST /api/callouts/218/callout_events

Parameters

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

Response

location: /api/callouts/218
201 Created

{
  "account_id": 446,
  "id": 218,
  "status": "running",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2024-11-20T11:03:55.954Z",
  "updated_at": "2024-11-20T11:03:55.966Z",
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}

Delete a Callout

Request

curl "https://scfm.somleng.org/api/callouts/216" -d '' -X DELETE \
    -H "Authorization: Bearer 1FhZXL30ftCK3uSBDjUoBMTvcG1DsY6Vjo9nHYgKHRk"

Endpoint

DELETE /api/callouts/:id

DELETE /api/callouts/216

Parameters

None known.

Response

location: /api/callouts
204 No Content

List all Callouts

Request

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

Endpoint

GET /api/callouts

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 208,
    "status": "initialized",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2024-11-20T11:03:55.795Z",
    "updated_at": "2024-11-20T11:03:55.795Z",
    "account_id": 438,
    "audio_url": null,
    "settings": {
    },
    "created_by_id": null
  }
]

Retrieve a Callout

Request

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

Endpoint

GET /api/callouts/:id

GET /api/callouts/214

Parameters

None known.

Response

location: /api/callouts/214
200 OK

{
  "id": 214,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2024-11-20T11:03:55.867Z",
  "updated_at": "2024-11-20T11:03:55.867Z",
  "account_id": 442,
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}

Update a Callout

Request

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

Endpoint

PATCH /api/callouts/:id

PATCH /api/callouts/215

Parameters

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

None known.

Response

location: /api/callouts/215
204 No Content

Contacts

Create a Contact

Request

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

Endpoint

POST /api/contacts

POST /api/contacts

Parameters

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

Response

location: /api/contacts/221
201 Created

{
  "id": 221,
  "msisdn": "+252662346012",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2024-11-20T11:03:56.096Z",
  "updated_at": "2024-11-20T11:03:56.096Z",
  "account_id": 453
}

Create or update a Contact

Creates or updates a contact. If a contact is found with the msisdn, it is updated, otherwise it is created.

Request

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

Endpoint

POST /api/contact_data

POST /api/contact_data

Parameters

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

None known.

Response

location: /api/contacts/225
201 Created

{
  "id": 225,
  "msisdn": "+252662346016",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2024-11-20T11:03:56.179Z",
  "updated_at": "2024-11-20T11:03:56.179Z",
  "account_id": 458
}

Delete a Contact

Request

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

Endpoint

DELETE /api/contacts/:id

DELETE /api/contacts/227

Parameters

None known.

Response

location: /api/contacts
204 No Content

Filter contacts by metadata

Filters contacts by the metadata provided in the query.

Available operators: in, any, lt, lteq, gt, gteq, exists

Request

curl -g "https://scfm.somleng.org/api/contacts?q[metadata][registered_districts.any][]=1402&q[metadata][registered_districts.any][]=1401" -X GET \
    -H "Authorization: Bearer uTF8h57rATb2Oav3oSUyTnE9tm8Ola7dSr9CYabL_3Q"

Endpoint

GET /api/contacts

GET /api/contacts?q[metadata][registered_districts.any][]=1402&q[metadata][registered_districts.any][]=1401

Parameters

q: {"metadata"=>{"registered_districts.any"=>["1402", "1401"]}}

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 217,
    "msisdn": "+252662346008",
    "metadata": {
      "registered_districts": [
        "1401"
      ]
    },
    "created_at": "2024-11-20T11:03:56.043Z",
    "updated_at": "2024-11-20T11:03:56.043Z",
    "account_id": 451
  }
]

List all Contacts

Request

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

Endpoint

GET /api/contacts

GET /api/contacts

Parameters

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 215,
    "msisdn": "+252662346006",
    "metadata": {
    },
    "created_at": "2024-11-20T11:03:56.020Z",
    "updated_at": "2024-11-20T11:03:56.020Z",
    "account_id": 449
  }
]

Retrieve a Contact

Request

curl -g "https://scfm.somleng.org/api/contacts/222" -X GET \
    -H "Authorization: Bearer p-DFd4Ld3zWwO17tHUh4OheZZ1gBYYzKCv4c0jpb1WU"

Endpoint

GET /api/contacts/:id

GET /api/contacts/222

Parameters

None known.

Response

location: /api/contacts/222
200 OK

{
  "id": 222,
  "msisdn": "+252662346013",
  "metadata": {
  },
  "created_at": "2024-11-20T11:03:56.121Z",
  "updated_at": "2024-11-20T11:03:56.121Z",
  "account_id": 455
}

Update a Contact

Request

curl "https://scfm.somleng.org/api/contacts/223" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Authorization: Bearer J2IO4FwJfzXIIcCccd5kNuh-swrb-XRwuGvFQNx8VeE"

Endpoint

PATCH /api/contacts/:id

PATCH /api/contacts/223

Parameters

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

None known.

Response

location: /api/contacts/223
204 No Content

Phone Calls

List all Phone Calls

Request

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

Endpoint

GET /api/phone_calls

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 148,
    "callout_participation_id": 175,
    "contact_id": 230,
    "status": "created",
    "msisdn": "+252662346021",
    "remote_call_id": "92186872-6229-49f2-b921-4377957e5fb8",
    "remote_status": null,
    "remote_direction": null,
    "remote_error_message": null,
    "metadata": {
      "foo": "bar"
    },
    "remote_response": {
    },
    "remote_queue_response": {
    },
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "remotely_queued_at": null,
    "created_at": "2024-11-20T11:03:56.264Z",
    "updated_at": "2024-11-20T11:03:56.264Z",
    "duration": 0,
    "lock_version": 0,
    "account_id": 462,
    "remote_status_fetch_queued_at": null,
    "callout_id": 223
  }
]

Retrieve a Phone Call

Request

curl -g "https://scfm.somleng.org/api/phone_calls/157" -X GET \
    -H "Authorization: Bearer JhVL_tfJt3WmvPbrQQ31jEJqdU5PjBjFX63r7AJ1_qw"

Endpoint

GET /api/phone_calls/:id

GET /api/phone_calls/157

Parameters

None known.

Response

location: /api/phone_calls/157
200 OK

{
  "id": 157,
  "callout_participation_id": 184,
  "contact_id": 239,
  "status": "created",
  "msisdn": "+252662346030",
  "remote_call_id": "3311ec2f-6a5b-4fcb-8e8f-67bc63398b29",
  "remote_status": null,
  "remote_direction": null,
  "remote_error_message": null,
  "metadata": {
  },
  "remote_response": {
  },
  "remote_queue_response": {
  },
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "remotely_queued_at": null,
  "created_at": "2024-11-20T11:03:56.425Z",
  "updated_at": "2024-11-20T11:03:56.425Z",
  "duration": 0,
  "lock_version": 0,
  "account_id": 468,
  "remote_status_fetch_queued_at": null,
  "callout_id": 232
}

Recordings

List Recordings

Request

curl -g "https://scfm.somleng.org/api/recordings?q[created_at_or_after]=2024-11-20T11%3A03%3A56Z" -X GET \
    -H "Authorization: Bearer gaahNt2c6J58akhQXoUTZCWH47EeW-7Q19M5c6VZnAM"

Endpoint

GET /api/recordings

GET /api/recordings?q[created_at_or_after]=2024-11-20T11%3A03%3A56Z

Parameters

q: {"created_at_or_after"=>"2024-11-20T11:03:56Z"}

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 1,
    "phone_call_id": 158,
    "account_id": 469,
    "contact_id": 240,
    "external_recording_id": "004b9bfe-951b-415d-bead-ce78b1815f73",
    "external_recording_url": "https://api.somleng.org/2010-04-01/Accounts/1a043c01-60df-47f0-873c-c9b22494999b/Calls/47b94987-ec5b-456f-bfd3-39d06dff0bc1/Recordings/004b9bfe-951b-415d-bead-ce78b1815f73",
    "duration": 15,
    "created_at": "2024-11-20T11:03:56.478Z",
    "updated_at": "2024-11-20T11:03:56.485Z"
  }
]

Retrieve a Recording

Request

curl -g "https://scfm.somleng.org/api/recordings/4" -X GET \
    -H "Authorization: Bearer eh8FX_aSH32WQxb0wg-yhdiyvO0BCKOOSaUIdzH8gc8"

Endpoint

GET /api/recordings/:id

GET /api/recordings/4

Parameters

None known.

Response

location: /api/recordings/4
200 OK

{
  "id": 4,
  "phone_call_id": 161,
  "account_id": 477,
  "contact_id": 243,
  "external_recording_id": "68fbdd4d-3e20-41a1-afb1-65d9add94a75",
  "external_recording_url": "https://api.somleng.org/2010-04-01/Accounts/7a83a999-35d5-4f61-a921-99a8fa6d436c/Calls/3c98d5cc-98f8-457a-9ec2-bf8727f5bead/Recordings/68fbdd4d-3e20-41a1-afb1-65d9add94a75",
  "duration": 15,
  "created_at": "2024-11-20T11:03:56.613Z",
  "updated_at": "2024-11-20T11:03:56.618Z"
}

Retrieve a recording as mp3

Request

curl -g "https://scfm.somleng.orgapi/recordings/5.mp3" -X GET \
    -H "Authorization: Bearer 42gkeqlLeicwLAfOcmzWvAMb2cQFP3RyTXfTnAdEWQ0"

Endpoint

GET api/recordings/:id.mp3

GET api/recordings/5.mp3

Parameters

None known.

Response

location: http://example.org/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiIwdG96aGwxd2gzamJzNHQ2d3o3Mjd5OG42cnVqIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRlc3QubXAzXCI7IGZpbGVuYW1lKj1VVEYtOCcndGVzdC5tcDMiLCJjb250ZW50X3R5cGUiOiJhdWRpby9tcGVnIiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI0LTExLTIwVDExOjA4OjU2LjY3N1oiLCJwdXIiOiJibG9iX2tleSJ9fQ==--dc54d6d465b754c3d163b2eb595111d537004735/test.mp3
302 Found

Remote Phone Call Events

Remote Phone Call Events are created by Somleng or Twilio Webhooks, when an event happens in a Phone Call. Setup your Somleng or Twilio Webhook endpoint to point to /api/remote_phone_call_events

List all Remote Phone Call Events

Request

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

Endpoint

GET /api/remote_phone_call_events

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 78,
    "phone_call_id": 163,
    "details": {
      "To": "345",
      "From": "252662346037",
      "CallSid": "a62ab734-edce-4886-adf6-fd7809365c28",
      "Direction": "inbound",
      "AccountSid": "ce1137a1-7e35-4df9-afbf-1d5043fd121b",
      "ApiVersion": "2010-04-01",
      "CallStatus": "completed"
    },
    "metadata": {
      "foo": "bar"
    },
    "remote_call_id": "a62ab734-edce-4886-adf6-fd7809365c28",
    "remote_direction": "inbound",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "created_at": "2024-11-20T11:03:56.694Z",
    "updated_at": "2024-11-20T11:03:56.694Z",
    "call_duration": 0
  }
]

Retrieve a Remote Phone Call Event

Request

curl -g "https://scfm.somleng.org/api/remote_phone_call_events/89" -X GET \
    -H "Authorization: Bearer kQwSPmwg89QBX8FAgqyjLtEs_Glz-lS8OBo3DXe2Z6U"

Endpoint

GET /api/remote_phone_call_events/:id

GET /api/remote_phone_call_events/89

Parameters

None known.

Response

location: /api/remote_phone_call_events/89
200 OK

{
  "id": 89,
  "phone_call_id": 174,
  "details": {
    "To": "345",
    "From": "252662346059",
    "CallSid": "3e361cf9-4626-4a76-a2f7-503279565721",
    "Direction": "inbound",
    "AccountSid": "74084ee3-a6d8-4911-9946-dff8a928d51e",
    "ApiVersion": "2010-04-01",
    "CallStatus": "completed"
  },
  "metadata": {
  },
  "remote_call_id": "3e361cf9-4626-4a76-a2f7-503279565721",
  "remote_direction": "inbound",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "created_at": "2024-11-20T11:03:56.921Z",
  "updated_at": "2024-11-20T11:03:56.921Z",
  "call_duration": 0
}

Update a Remote Phone Call Event

Request

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

Endpoint

PATCH /api/remote_phone_call_events/:id

PATCH /api/remote_phone_call_events/90

Parameters

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

None known.

Response

location: /api/remote_phone_call_events/90
204 No Content

Shared API Features

Filtering, Sorting and Pagination

All index requests can be filtered and sorted by using the q and sort parameters. Responses are paginated. The maxiumum number of items displayed for a single request is 25. This can be verified by the Per-Page response header. The actual number of items will appear in the Total header. If there are more than 25 items then you'll see a Link header with links to the first, last, next and previous pages. The links are formatted according to RFC-8288.

Request

curl -g "https://scfm.somleng.org/api/contacts?q[metadata][gender]=f&q[metadata][date_of_birth.date.gt]=2022-01-01&q[metadata][date_of_birth.date.lt]=2022-02-01&q[created_at_after]=2024-11-19&sort=-id%2Ccreated_at" -X GET \
    -H "Authorization: Bearer MPSj9TyY3XNaKUXvGvrAxMxfe7y4HcuSJgA-M1mylP0"

Endpoint

GET /api/contacts

GET /api/contacts?q[metadata][gender]=f&q[metadata][date_of_birth.date.gt]=2022-01-01&q[metadata][date_of_birth.date.lt]=2022-02-01&q[created_at_after]=2024-11-19&sort=-id%2Ccreated_at

Parameters

q: {"metadata"=>{"gender"=>"f", "date_of_birth.date.gt"=>"2022-01-01", "date_of_birth.date.lt"=>"2022-02-01"}, "created_at_after"=>"2024-11-19"}
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": 283,
    "msisdn": "+252662346087",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.020Z",
    "updated_at": "2024-11-20T11:03:57.020Z",
    "account_id": 489
  },
  {
    "id": 282,
    "msisdn": "+252662346086",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.018Z",
    "updated_at": "2024-11-20T11:03:57.018Z",
    "account_id": 489
  },
  {
    "id": 281,
    "msisdn": "+252662346085",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.015Z",
    "updated_at": "2024-11-20T11:03:57.015Z",
    "account_id": 489
  },
  {
    "id": 280,
    "msisdn": "+252662346084",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.013Z",
    "updated_at": "2024-11-20T11:03:57.013Z",
    "account_id": 489
  },
  {
    "id": 279,
    "msisdn": "+252662346083",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.011Z",
    "updated_at": "2024-11-20T11:03:57.011Z",
    "account_id": 489
  },
  {
    "id": 278,
    "msisdn": "+252662346082",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.010Z",
    "updated_at": "2024-11-20T11:03:57.010Z",
    "account_id": 489
  },
  {
    "id": 277,
    "msisdn": "+252662346081",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.008Z",
    "updated_at": "2024-11-20T11:03:57.008Z",
    "account_id": 489
  },
  {
    "id": 276,
    "msisdn": "+252662346080",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.006Z",
    "updated_at": "2024-11-20T11:03:57.006Z",
    "account_id": 489
  },
  {
    "id": 275,
    "msisdn": "+252662346079",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.004Z",
    "updated_at": "2024-11-20T11:03:57.004Z",
    "account_id": 489
  },
  {
    "id": 274,
    "msisdn": "+252662346078",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.002Z",
    "updated_at": "2024-11-20T11:03:57.002Z",
    "account_id": 489
  },
  {
    "id": 273,
    "msisdn": "+252662346077",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:57.000Z",
    "updated_at": "2024-11-20T11:03:57.000Z",
    "account_id": 489
  },
  {
    "id": 272,
    "msisdn": "+252662346076",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.998Z",
    "updated_at": "2024-11-20T11:03:56.998Z",
    "account_id": 489
  },
  {
    "id": 271,
    "msisdn": "+252662346075",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.996Z",
    "updated_at": "2024-11-20T11:03:56.996Z",
    "account_id": 489
  },
  {
    "id": 270,
    "msisdn": "+252662346074",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.994Z",
    "updated_at": "2024-11-20T11:03:56.994Z",
    "account_id": 489
  },
  {
    "id": 269,
    "msisdn": "+252662346073",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.992Z",
    "updated_at": "2024-11-20T11:03:56.992Z",
    "account_id": 489
  },
  {
    "id": 268,
    "msisdn": "+252662346072",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.991Z",
    "updated_at": "2024-11-20T11:03:56.991Z",
    "account_id": 489
  },
  {
    "id": 267,
    "msisdn": "+252662346071",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.989Z",
    "updated_at": "2024-11-20T11:03:56.989Z",
    "account_id": 489
  },
  {
    "id": 266,
    "msisdn": "+252662346070",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.987Z",
    "updated_at": "2024-11-20T11:03:56.987Z",
    "account_id": 489
  },
  {
    "id": 265,
    "msisdn": "+252662346069",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.985Z",
    "updated_at": "2024-11-20T11:03:56.985Z",
    "account_id": 489
  },
  {
    "id": 264,
    "msisdn": "+252662346068",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.983Z",
    "updated_at": "2024-11-20T11:03:56.983Z",
    "account_id": 489
  },
  {
    "id": 263,
    "msisdn": "+252662346067",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.981Z",
    "updated_at": "2024-11-20T11:03:56.981Z",
    "account_id": 489
  },
  {
    "id": 262,
    "msisdn": "+252662346066",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.979Z",
    "updated_at": "2024-11-20T11:03:56.979Z",
    "account_id": 489
  },
  {
    "id": 261,
    "msisdn": "+252662346065",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.977Z",
    "updated_at": "2024-11-20T11:03:56.977Z",
    "account_id": 489
  },
  {
    "id": 260,
    "msisdn": "+252662346064",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.975Z",
    "updated_at": "2024-11-20T11:03:56.975Z",
    "account_id": 489
  },
  {
    "id": 259,
    "msisdn": "+252662346063",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2024-11-20T11:03:56.973Z",
    "updated_at": "2024-11-20T11:03:56.973Z",
    "account_id": 489
  }
]

Metadata

Metadata is useful for storing additional, structured information on an object. As an example, you could store the contact's name and gender on the Contact object.

Request

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

Endpoint

PATCH /api/contacts/:id

PATCH /api/contacts/285

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

Users

Create a User

Request

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

Endpoint

POST /api/users

POST /api/users

Parameters

{
  "email": "user22@example.com",
  "password": "secret123",
  "metadata": {
    "foo": "bar"
  }
}
Name Description
email required The email address of the user
password required The initial password of the user. The user can change their password when they log in.

Response

location: /api/users/15
201 Created

{
  "id": 15,
  "account_id": 495,
  "metadata": {
    "foo": "bar"
  },
  "email": "user22@example.com",
  "created_at": "2024-11-20T11:03:57.129Z",
  "updated_at": "2024-11-20T11:03:57.129Z",
  "locale": "en"
}

Create a User Event

Request

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

Endpoint

POST /api/users/:user_id/user_events

POST /api/users/20/user_events

Parameters

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

Response

location: /api/users/20
201 Created

{
  "account_id": 501,
  "id": 20,
  "metadata": {
  },
  "email": "user27@example.com",
  "created_at": "2024-11-20T11:03:57.232Z",
  "updated_at": "2024-11-20T11:03:57.240Z",
  "locale": "en"
}

Delete a User

Request

curl "https://scfm.somleng.org/api/users/19" -d '' -X DELETE \
    -H "Authorization: Bearer 0CX9pW31qVj8Sv0lq3HnBtIJ4t_w9I3g6bNxwIHOjkM"

Endpoint

DELETE /api/users/:id

DELETE /api/users/19

Parameters

None known.

Response

location: /api/users
204 No Content

List all Users

Request

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

Endpoint

GET /api/users

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

Parameters

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

None known.

Response

per-page: 25
total: 1
200 OK

[
  {
    "id": 10,
    "account_id": 491,
    "metadata": {
      "foo": "bar"
    },
    "email": "user17@example.com",
    "created_at": "2024-11-20T11:03:57.064Z",
    "updated_at": "2024-11-20T11:03:57.064Z",
    "locale": "en"
  }
]

Retrieve a User

Request

curl -g "https://scfm.somleng.org/api/users/17" -X GET \
    -H "Authorization: Bearer Wk0K7xZ7Il6MqzQ-JTtWB8QnX3o0RzACTBTK26iRWSg"

Endpoint

GET /api/users/:id

GET /api/users/17

Parameters

None known.

Response

location: /api/users/17
200 OK

{
  "id": 17,
  "account_id": 498,
  "metadata": {
  },
  "email": "user24@example.com",
  "created_at": "2024-11-20T11:03:57.165Z",
  "updated_at": "2024-11-20T11:03:57.165Z",
  "locale": "en"
}

Update a User

Request

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

Endpoint

PATCH /api/users/:id

PATCH /api/users/18

Parameters

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

None known.

Response

location: /api/users/18
204 No Content
cURL