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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer Al5TsJQuPBGJ48k6oEqXxyAm-NDqTlWeY1Tzrletu3A"

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": "s1zAqwymVXjswCjEQlJW5yMb0XauxRLR2vkpqt2BBPs",
  "created_at": "2023-09-18T06:34:48.708Z",
  "updated_at": "2023-09-18T06:34:48.710Z",
  "metadata": {
    "foo": "bar"
  },
  "permissions": [
    "contacts_write"
  ]
}

Delete an Access Token

Request

curl "https://scfm.somleng.org/api/access_tokens/21" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer n0ps0RLcjTiY07GYrmZaa78nJ4r2GD9ZftTKgeaOYVc"

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer RgP9b1Rm2wNxw936GEf6qEUEDmzg8dwFQl2ZWqUfMRQ"

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": "p0ZIwMEX6xCp-Tj8LKzFcN7nddLI9qu7bQe3ppZV4hE",
    "created_at": "2023-09-18T06:34:48.609Z",
    "updated_at": "2023-09-18T06:34:48.611Z",
    "metadata": {
      "foo": "bar"
    },
    "permissions": [

    ]
  }
]

Retrieve an Access Token

Request

curl -g "https://scfm.somleng.org/api/access_tokens/19" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer FR4BO_WjOEvpLwjcDDKjtb-ltIgQ4Qnlw2LeNQ_IzRU"

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": "FR4BO_WjOEvpLwjcDDKjtb-ltIgQ4Qnlw2LeNQ_IzRU",
  "created_at": "2023-09-18T06:34:48.754Z",
  "updated_at": "2023-09-18T06:34:48.755Z",
  "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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer WK3LSA6p6-gD8Tnp9atyM_nB2zB_orQN39iQvEeOD7I"

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer mfoUDJ4k3niQC6CWnaZ9sE0npmo_cpRHrTw-uUUV8P4"

Endpoint

GET /api/account

GET /api/account

Parameters

None known.

Response

Location: /api/accounts/387
200 OK

{
  "id": 387,
  "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": "2023-09-18T06:34:48.842Z",
  "updated_at": "2023-09-18T06:34:48.842Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null,
  "phone_calls_count": 0,
  "contacts_count": 0
}

Update Account Details

Request

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

Endpoint

PATCH /api/account

PATCH /api/account

Parameters

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

None known.

Response

Location: /api/accounts/388
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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer k4nQ2d9gqGjWNWW9PN9pX3rLSXtCtKqukL69aYVsjBs"

Endpoint

POST /api/accounts

POST /api/accounts

Parameters

None known.

Response

Location: /api/accounts/393
201 Created

{
  "id": 393,
  "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": "2023-09-18T06:34:48.927Z",
  "updated_at": "2023-09-18T06:34:48.927Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null,
  "phone_calls_count": 0,
  "contacts_count": 0
}

Delete an Account

Request

curl "https://scfm.somleng.org/api/accounts/398" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer NRk86KxLryXyf4LrmLQNPDO1zaMgv9a7Y2TBLv_qoXc"

Endpoint

DELETE /api/accounts/:id

DELETE /api/accounts/398

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer Roc7vj7MFCWFVx3el9AuxoCF8EftQFtD28VUqspJdg0"

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": 389,
    "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": "2023-09-18T06:34:48.882Z",
    "updated_at": "2023-09-18T06:34:48.882Z",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "platform_provider_name": null,
    "somleng_api_host": null,
    "somleng_api_base_url": null,
    "phone_calls_count": 0,
    "contacts_count": 0
  }
]

Retrieve an Account

Request

curl -g "https://scfm.somleng.org/api/accounts/394" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 9NSwYd1p9WZWpWcSrR2JAM4ml1ZLruC0Iz2l6l_LLlI"

Endpoint

GET /api/accounts/:id

GET /api/accounts/394

Parameters

None known.

Response

Location: /api/accounts/394
200 OK

{
  "id": 394,
  "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": "2023-09-18T06:34:48.934Z",
  "updated_at": "2023-09-18T06:34:48.934Z",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "platform_provider_name": null,
  "somleng_api_host": null,
  "somleng_api_base_url": null,
  "phone_calls_count": 0,
  "contacts_count": 0
}

Update an Account

Request

curl "https://scfm.somleng.org/api/accounts/396" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "fa855a55-4a3b-472a-b765-1454b621c69e",
  "twilio_auth_token": "b60502a9-ac82-4a81-8eb4-ec38824aab50",
  "somleng_auth_token": "aac67fe0-8b81-4991-9fc6-8300c1992bd9",
  "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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer ZfO2WyJ-6ZP2b9sLJmeteUqgT0IfwI-1S4W1d9Au4Xk"

Endpoint

PATCH /api/accounts/:id

PATCH /api/accounts/396

Parameters

{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace",
  "twilio_account_sid": "AC8",
  "somleng_account_sid": "fa855a55-4a3b-472a-b765-1454b621c69e",
  "twilio_auth_token": "b60502a9-ac82-4a81-8eb4-ec38824aab50",
  "somleng_auth_token": "aac67fe0-8b81-4991-9fc6-8300c1992bd9",
  "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/396
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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer UmFVZlqAmsw8Xl1f77mfvXSabLu7xg6U5E9YnaMIork"

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": 187,
  "parameters": {
  },
  "metadata": {
  },
  "status": "queued",
  "created_at": "2023-09-18T06:34:49.285Z",
  "updated_at": "2023-09-18T06:34:49.285Z",
  "account_id": 413,
  "type": "BatchOperation::CalloutPopulation"
}

Delete a Batch Operation

Request

curl "https://scfm.somleng.org/api/batch_operations/26" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 2iblVqGT2mploAugEk_VwwJJVwHUjUfr4UwvePDeOEw"

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]=177" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer khJMMJvmsYrnf7iq8Dkax5UuIFTVq_lVOGhzsZSRCgc"

Endpoint

GET /api/batch_operations

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

Parameters

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

None known.

Response

Per-Page: 25
Total: 1
200 OK

[
  {
    "id": 20,
    "callout_id": 177,
    "parameters": {
    },
    "metadata": {
    },
    "status": "preview",
    "created_at": "2023-09-18T06:34:49.048Z",
    "updated_at": "2023-09-18T06:34:49.048Z",
    "account_id": 402,
    "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": 180,
  "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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer iy1dVkG848TVCt78iqhhiJvzgZmrCeStXXPeJwCuLvk"

Endpoint

POST /api/batch_operations

POST /api/batch_operations

Parameters

{
  "callout_id": 180,
  "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": 180,
  "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": "2023-09-18T06:34:49.100Z",
  "updated_at": "2023-09-18T06:34:49.100Z",
  "account_id": 404,
  "type": "BatchOperation::CalloutPopulation"
}

Retrieve a Batch Operation

Request

curl -g "https://scfm.somleng.org/api/batch_operations/24" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer pAKYoMtaql2FxtIFWfcEhyyh9O6uoLRNHATRtkkKQi4"

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": 182,
  "parameters": {
  },
  "metadata": {
  },
  "status": "preview",
  "created_at": "2023-09-18T06:34:49.163Z",
  "updated_at": "2023-09-18T06:34:49.163Z",
  "account_id": 407,
  "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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer Jv5F_4KdfqxLBLnewuANdoF4d87tTYYZv-f3RaVlKcw"

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/196/callout_participations" -d '{
  "contact_id": 200,
  "msisdn": "252662345984",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer -mAJKBbkMygKelfK3xwBwYj3lwbiKsQ4QPl-ErPQavw"

Endpoint

POST /api/callouts/:callout_id/callout_participations

POST /api/callouts/196/callout_participations

Parameters

{
  "contact_id": 200,
  "msisdn": "252662345984",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  }
}

None known.

Response

Location: /api/callout_participations/160
201 Created

{
  "id": 160,
  "callout_id": 196,
  "contact_id": 200,
  "callout_population_id": null,
  "msisdn": "+252662345984",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2023-09-18T06:34:49.511Z",
  "updated_at": "2023-09-18T06:34:49.511Z",
  "answered": false,
  "phone_calls_count": 0
}

Create a Callout Participation with invalid data

Request

curl "https://scfm.somleng.org/api/callouts/197/callout_participations" -d '' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer Z0obrSMkFy9mJuo794NO7gJiq7rRPKAKev9P26nNbIQ"

Endpoint

POST /api/callouts/:callout_id/callout_participations

POST /api/callouts/197/callout_participations

Parameters

None known.

Response


422 Unprocessable Entity

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

Delete a Callout Participation

Request

curl "https://scfm.somleng.org/api/callout_participations/163" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer TjJvnz05XH-9FZ_9YRLyQYwbQdqSc9jpjplMAv6v9g4"

Endpoint

DELETE /api/callout_participations/:id

DELETE /api/callout_participations/163

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/164" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer GaXH2BBe_Xue59UDj8nQ-qk3PuRHKYGRpX48vPDK5OI"

Endpoint

DELETE /api/callout_participations/:id

DELETE /api/callout_participations/164

Parameters

None known.

Response


422 Unprocessable Entity

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

List all Callout Participations

Request

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

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": 153,
    "callout_id": 189,
    "contact_id": 193,
    "callout_population_id": null,
    "msisdn": "+252662345976",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2023-09-18T06:34:49.355Z",
    "updated_at": "2023-09-18T06:34:49.355Z",
    "answered": false,
    "phone_calls_count": 0
  }
]

Retrieve a Callout Participation

Request

curl -g "https://scfm.somleng.org/api/callout_participations/161" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 1vA-ZHkx_FboOWF261T-Mv8I9fxmg70taOOLG6rDSRU"

Endpoint

GET /api/callout_participations/:id

GET /api/callout_participations/161

Parameters

None known.

Response

Location: /api/callout_participations/161
200 OK

{
  "id": 161,
  "callout_id": 198,
  "contact_id": 201,
  "callout_population_id": null,
  "msisdn": "+252662345985",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2023-09-18T06:34:49.560Z",
  "updated_at": "2023-09-18T06:34:49.560Z",
  "answered": false,
  "phone_calls_count": 0
}

Update a Callout Participation

Request

curl "https://scfm.somleng.org/api/callout_participations/162" -d '{
  "contact_id": 203,
  "msisdn": "252662345988",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer mWZ6C7Ftnfm4paOUu9vE_v6yfbq0ptfys4hAC4QYXvw"

Endpoint

PATCH /api/callout_participations/:id

PATCH /api/callout_participations/162

Parameters

{
  "contact_id": 203,
  "msisdn": "252662345988",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}

None known.

Response

Location: /api/callout_participations/162
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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer hmICpDvmWVUq9EisoGdjugL0xhtdh-oBELS0eJB82Hc"

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

{
  "id": 207,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2023-09-18T06:34:49.769Z",
  "updated_at": "2023-09-18T06:34:49.769Z",
  "account_id": 429,
  "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/212/callout_events" -d '{
  "event": "start"
}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 74SY7JKzrI-573EDSNQrxvos8ru5ZEt0BK32wJI0Nzs"

Endpoint

POST /api/callouts/:callout_id/callout_events

POST /api/callouts/212/callout_events

Parameters

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

Response

Location: /api/callouts/212
201 Created

{
  "account_id": 434,
  "id": 212,
  "status": "running",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2023-09-18T06:34:49.906Z",
  "updated_at": "2023-09-18T06:34:49.922Z",
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}

Delete a Callout

Request

curl "https://scfm.somleng.org/api/callouts/210" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer kHEl4ETpLO20ogWVNhDb9pPelvRtIcv9dAPSz4l5bPE"

Endpoint

DELETE /api/callouts/:id

DELETE /api/callouts/210

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer uraogo28GGPg0N04xBkRdugkRjcYIGp-zwoW3-KSMR4"

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": 202,
    "status": "initialized",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "metadata": {
      "foo": "bar"
    },
    "created_at": "2023-09-18T06:34:49.692Z",
    "updated_at": "2023-09-18T06:34:49.692Z",
    "account_id": 426,
    "audio_url": null,
    "settings": {
    },
    "created_by_id": null
  }
]

Retrieve a Callout

Request

curl -g "https://scfm.somleng.org/api/callouts/208" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer Ukxx4BCxAo-3Bw4s9ganHiH2tZ7JVMnRyImdqPJDfsY"

Endpoint

GET /api/callouts/:id

GET /api/callouts/208

Parameters

None known.

Response

Location: /api/callouts/208
200 OK

{
  "id": 208,
  "status": "initialized",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "metadata": {
  },
  "created_at": "2023-09-18T06:34:49.781Z",
  "updated_at": "2023-09-18T06:34:49.781Z",
  "account_id": 430,
  "audio_url": null,
  "settings": {
  },
  "created_by_id": null
}

Update a Callout

Request

curl "https://scfm.somleng.org/api/callouts/209" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer EnKhLKlVGAebkhhfV1b5_142FAKXouaHiH7LL8k0kPI"

Endpoint

PATCH /api/callouts/:id

PATCH /api/callouts/209

Parameters

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

None known.

Response

Location: /api/callouts/209
204 No Content

Contacts

Create a Contact

Request

curl "https://scfm.somleng.org/api/contacts" -d '{
  "msisdn": "252662345999",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer -E_hJsqSZ4Y_qZqMPIwWVtzqAd7Pkkrg0EDMpYjbE8w"

Endpoint

POST /api/contacts

POST /api/contacts

Parameters

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

Response

Location: /api/contacts/214
201 Created

{
  "id": 214,
  "msisdn": "+252662345999",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2023-09-18T06:34:50.094Z",
  "updated_at": "2023-09-18T06:34:50.094Z",
  "account_id": 441
}

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": "252662346003",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  }
}' -X POST \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer kOzecqP9xiVQ6kjRBUpIWxcxNg8HNnGD-DWJdr5TQUs"

Endpoint

POST /api/contact_data

POST /api/contact_data

Parameters

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

None known.

Response

Location: /api/contacts/218
201 Created

{
  "id": 218,
  "msisdn": "+252662346003",
  "metadata": {
    "gender": "f",
    "name": "Kate"
  },
  "created_at": "2023-09-18T06:34:50.192Z",
  "updated_at": "2023-09-18T06:34:50.192Z",
  "account_id": 446
}

Delete a Contact

Request

curl "https://scfm.somleng.org/api/contacts/220" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer u5l6iM7ryXt1UHbDv0Co1AWfMv2AhlVJNNZzYrdRXKA"

Endpoint

DELETE /api/contacts/:id

DELETE /api/contacts/220

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer upS5Cgqx1BJFY8cwi39iACjIZaEBhMLfA0YaRalvu9s"

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": 210,
    "msisdn": "+252662345995",
    "metadata": {
      "registered_districts": [
        "1401"
      ]
    },
    "created_at": "2023-09-18T06:34:50.022Z",
    "updated_at": "2023-09-18T06:34:50.022Z",
    "account_id": 439
  }
]

List all Contacts

Request

curl -g "https://scfm.somleng.org/api/contacts" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 0xnkGj6N_2X4lcXK4m-l4Nd1FxKHdO1uDaWDJSTZ1Ww"

Endpoint

GET /api/contacts

GET /api/contacts

Parameters

None known.

Response

Per-Page: 25
Total: 1
200 OK

[
  {
    "id": 208,
    "msisdn": "+252662345993",
    "metadata": {
    },
    "created_at": "2023-09-18T06:34:49.991Z",
    "updated_at": "2023-09-18T06:34:49.991Z",
    "account_id": 437
  }
]

Retrieve a Contact

Request

curl -g "https://scfm.somleng.org/api/contacts/215" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer hU5jrVVEq7jo76Eud4aFoUw5V1XI8nx3vmjLT5cDBQY"

Endpoint

GET /api/contacts/:id

GET /api/contacts/215

Parameters

None known.

Response

Location: /api/contacts/215
200 OK

{
  "id": 215,
  "msisdn": "+252662346000",
  "metadata": {
  },
  "created_at": "2023-09-18T06:34:50.123Z",
  "updated_at": "2023-09-18T06:34:50.123Z",
  "account_id": 443
}

Update a Contact

Request

curl "https://scfm.somleng.org/api/contacts/216" -d '{
  "metadata": {
    "bar": "foo"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer _nuaGLP7K6Ql1F7lU_1SKSutDvk8Zxt2WpuAli8pngc"

Endpoint

PATCH /api/contacts/:id

PATCH /api/contacts/216

Parameters

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

None known.

Response

Location: /api/contacts/216
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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer E2VaEYBpeyYj8R7W9Jv_02E_oDaNarW4CBGE16c1L1s"

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": 141,
    "callout_participation_id": 169,
    "contact_id": 223,
    "status": "created",
    "msisdn": "+252662346008",
    "remote_call_id": "978f690e-f890-4c78-9fcf-e0a8a8d8ad60",
    "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": "2023-09-18T06:34:50.301Z",
    "updated_at": "2023-09-18T06:34:50.301Z",
    "duration": 0,
    "lock_version": 0,
    "account_id": 450,
    "remote_status_fetch_queued_at": null,
    "callout_id": 217
  }
]

Retrieve a Phone Call

Request

curl -g "https://scfm.somleng.org/api/phone_calls/150" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer tz2Lhe-CQoa7zDG9ivxmt3PV44iIEtqoTcbXNli1Bf8"

Endpoint

GET /api/phone_calls/:id

GET /api/phone_calls/150

Parameters

None known.

Response

Location: /api/phone_calls/150
200 OK

{
  "id": 150,
  "callout_participation_id": 178,
  "contact_id": 232,
  "status": "created",
  "msisdn": "+252662346017",
  "remote_call_id": "58e51fc0-0867-4c3b-9cd7-36652aa23507",
  "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": "2023-09-18T06:34:50.523Z",
  "updated_at": "2023-09-18T06:34:50.523Z",
  "duration": 0,
  "lock_version": 0,
  "account_id": 456,
  "remote_status_fetch_queued_at": null,
  "callout_id": 226
}

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer 3z5gCuIDQn_mOqTiO_HxWm2Swhdn-facwuFOyHz5skY"

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": 71,
    "phone_call_id": 151,
    "details": {
      "To": "345",
      "From": "252662346019",
      "CallSid": "9a3e998d-f97b-49a2-b8a6-dfdc75718a44",
      "Direction": "inbound",
      "AccountSid": "6597df9d-ddd8-4f36-abba-325e63b81caa",
      "ApiVersion": "2010-04-01",
      "CallStatus": "completed"
    },
    "metadata": {
      "foo": "bar"
    },
    "remote_call_id": "9a3e998d-f97b-49a2-b8a6-dfdc75718a44",
    "remote_direction": "inbound",
    "call_flow_logic": "CallFlowLogic::HelloWorld",
    "created_at": "2023-09-18T06:34:50.565Z",
    "updated_at": "2023-09-18T06:34:50.565Z",
    "call_duration": 0
  }
]

Retrieve a Remote Phone Call Event

Request

curl -g "https://scfm.somleng.org/api/remote_phone_call_events/82" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer IwcfJKdXhF-PXTij3m-65_aV1FhMXIaDGx8cnQ9NS1I"

Endpoint

GET /api/remote_phone_call_events/:id

GET /api/remote_phone_call_events/82

Parameters

None known.

Response

Location: /api/remote_phone_call_events/82
200 OK

{
  "id": 82,
  "phone_call_id": 162,
  "details": {
    "To": "345",
    "From": "252662346041",
    "CallSid": "a6aaeb0e-6363-41e5-b469-50bcc8af16be",
    "Direction": "inbound",
    "AccountSid": "c597b421-bafa-45de-9795-9bef588e7fbe",
    "ApiVersion": "2010-04-01",
    "CallStatus": "completed"
  },
  "metadata": {
  },
  "remote_call_id": "a6aaeb0e-6363-41e5-b469-50bcc8af16be",
  "remote_direction": "inbound",
  "call_flow_logic": "CallFlowLogic::HelloWorld",
  "created_at": "2023-09-18T06:34:50.931Z",
  "updated_at": "2023-09-18T06:34:50.931Z",
  "call_duration": 0
}

Update a Remote Phone Call Event

Request

curl "https://scfm.somleng.org/api/remote_phone_call_events/83" -d '{
  "metadata": {
    "foo": "bar"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer RXT5nAuyfKMepYZOyT5QBwolehGQOv7EpI-3nz5jXZo"

Endpoint

PATCH /api/remote_phone_call_events/:id

PATCH /api/remote_phone_call_events/83

Parameters

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

None known.

Response

Location: /api/remote_phone_call_events/83
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]=2023-09-17&sort=-id%2Ccreated_at" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer abEtFgadQw3exelLFWZNP2kjXSyBhmWaItUKNy7rkIc"

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]=2023-09-17&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"=>"2023-09-17"}
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": 274,
    "msisdn": "+252662346070",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.234Z",
    "updated_at": "2023-09-18T06:34:51.234Z",
    "account_id": 470
  },
  {
    "id": 273,
    "msisdn": "+252662346069",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.231Z",
    "updated_at": "2023-09-18T06:34:51.231Z",
    "account_id": 470
  },
  {
    "id": 272,
    "msisdn": "+252662346068",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.228Z",
    "updated_at": "2023-09-18T06:34:51.228Z",
    "account_id": 470
  },
  {
    "id": 271,
    "msisdn": "+252662346067",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.224Z",
    "updated_at": "2023-09-18T06:34:51.224Z",
    "account_id": 470
  },
  {
    "id": 270,
    "msisdn": "+252662346066",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.221Z",
    "updated_at": "2023-09-18T06:34:51.221Z",
    "account_id": 470
  },
  {
    "id": 269,
    "msisdn": "+252662346065",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.217Z",
    "updated_at": "2023-09-18T06:34:51.217Z",
    "account_id": 470
  },
  {
    "id": 268,
    "msisdn": "+252662346064",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.214Z",
    "updated_at": "2023-09-18T06:34:51.214Z",
    "account_id": 470
  },
  {
    "id": 267,
    "msisdn": "+252662346063",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.211Z",
    "updated_at": "2023-09-18T06:34:51.211Z",
    "account_id": 470
  },
  {
    "id": 266,
    "msisdn": "+252662346062",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.207Z",
    "updated_at": "2023-09-18T06:34:51.207Z",
    "account_id": 470
  },
  {
    "id": 265,
    "msisdn": "+252662346061",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.204Z",
    "updated_at": "2023-09-18T06:34:51.204Z",
    "account_id": 470
  },
  {
    "id": 264,
    "msisdn": "+252662346060",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.201Z",
    "updated_at": "2023-09-18T06:34:51.201Z",
    "account_id": 470
  },
  {
    "id": 263,
    "msisdn": "+252662346059",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.197Z",
    "updated_at": "2023-09-18T06:34:51.197Z",
    "account_id": 470
  },
  {
    "id": 262,
    "msisdn": "+252662346058",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.194Z",
    "updated_at": "2023-09-18T06:34:51.194Z",
    "account_id": 470
  },
  {
    "id": 261,
    "msisdn": "+252662346057",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.191Z",
    "updated_at": "2023-09-18T06:34:51.191Z",
    "account_id": 470
  },
  {
    "id": 260,
    "msisdn": "+252662346056",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.187Z",
    "updated_at": "2023-09-18T06:34:51.187Z",
    "account_id": 470
  },
  {
    "id": 259,
    "msisdn": "+252662346055",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.184Z",
    "updated_at": "2023-09-18T06:34:51.184Z",
    "account_id": 470
  },
  {
    "id": 258,
    "msisdn": "+252662346054",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.180Z",
    "updated_at": "2023-09-18T06:34:51.180Z",
    "account_id": 470
  },
  {
    "id": 257,
    "msisdn": "+252662346053",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.177Z",
    "updated_at": "2023-09-18T06:34:51.177Z",
    "account_id": 470
  },
  {
    "id": 256,
    "msisdn": "+252662346052",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.174Z",
    "updated_at": "2023-09-18T06:34:51.174Z",
    "account_id": 470
  },
  {
    "id": 255,
    "msisdn": "+252662346051",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.170Z",
    "updated_at": "2023-09-18T06:34:51.170Z",
    "account_id": 470
  },
  {
    "id": 254,
    "msisdn": "+252662346050",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.167Z",
    "updated_at": "2023-09-18T06:34:51.167Z",
    "account_id": 470
  },
  {
    "id": 253,
    "msisdn": "+252662346049",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.163Z",
    "updated_at": "2023-09-18T06:34:51.163Z",
    "account_id": 470
  },
  {
    "id": 252,
    "msisdn": "+252662346048",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.160Z",
    "updated_at": "2023-09-18T06:34:51.160Z",
    "account_id": 470
  },
  {
    "id": 251,
    "msisdn": "+252662346047",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.157Z",
    "updated_at": "2023-09-18T06:34:51.157Z",
    "account_id": 470
  },
  {
    "id": 250,
    "msisdn": "+252662346046",
    "metadata": {
      "gender": "f",
      "date_of_birth": "2022-01-15"
    },
    "created_at": "2023-09-18T06:34:51.153Z",
    "updated_at": "2023-09-18T06:34:51.153Z",
    "account_id": 470
  }
]

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/276" -d '{
  "metadata": {
    "name": "Kate"
  },
  "metadata_merge_mode": "replace"
}' -X PATCH \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer NBBDKNR1KNXRGSnXKKZaDlx7wihNhsoWpsgnuInx17M"

Endpoint

PATCH /api/contacts/:id

PATCH /api/contacts/276

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/276
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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer _G4Mr4Npzw_FWVU4S2cWTw1R3_tz-D2eaB5J_8nlKT4"

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": 476,
  "metadata": {
    "foo": "bar"
  },
  "email": "user22@example.com",
  "created_at": "2023-09-18T06:34:51.388Z",
  "updated_at": "2023-09-18T06:34:51.388Z",
  "locale": "en"
}

Create a User Event

Request

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

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": 482,
  "id": 20,
  "metadata": {
  },
  "email": "user27@example.com",
  "created_at": "2023-09-18T06:34:51.510Z",
  "updated_at": "2023-09-18T06:34:51.520Z",
  "locale": "en"
}

Delete a User

Request

curl "https://scfm.somleng.org/api/users/19" -d '' -X DELETE \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer 5B0vAHpJ2vgkCCA3X-g2ZkUuwiCx2-pyK0hXAN2RIK0"

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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer M-Mkv7hTCQoVmH-LOqqFpkRh3S8NYkRmE5IvXQ9dFc0"

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": 472,
    "metadata": {
      "foo": "bar"
    },
    "email": "user17@example.com",
    "created_at": "2023-09-18T06:34:51.301Z",
    "updated_at": "2023-09-18T06:34:51.301Z",
    "locale": "en"
  }
]

Retrieve a User

Request

curl -g "https://scfm.somleng.org/api/users/17" -X GET \
    -H "Version: HTTP/1.0" \
    -H "Authorization: Bearer NkyKNcdAP4BvgDkOoEaCRtFcUSiaodTquOJTvIVR_LY"

Endpoint

GET /api/users/:id

GET /api/users/17

Parameters

None known.

Response

Location: /api/users/17
200 OK

{
  "id": 17,
  "account_id": 479,
  "metadata": {
  },
  "email": "user24@example.com",
  "created_at": "2023-09-18T06:34:51.432Z",
  "updated_at": "2023-09-18T06:34:51.432Z",
  "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 "Version: HTTP/1.0" \
    -H "Authorization: Bearer nUZB_6-0P74iW8UopovBjXi0xO253DDB8SPSVnnLnSo"

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