Notify Service v1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Service for contacting respondents via Gov Notify SMS messages

Base URLs:

• http://localhost:8162

email-fulfilment-endpoint

emailFulfilment

Code samples

# You can also use wget
curl -X POST http://localhost:8162/email-fulfilment \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST http://localhost:8162/email-fulfilment HTTP/1.1
Host: localhost:8162
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "header": {
    "channel": "RH",
    "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
    "originatingUser": "fred.bloggs@ons.gov.uk",
    "source": "Survey Enquiry Line API"
  },
  "payload": {
    "emailFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "email": "example@example.com",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "uacMetadata": null
    },
    "smsFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "phoneNumber": "+447123456789",
      "uacMetadata": null
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('http://localhost:8162/email-fulfilment',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'http://localhost:8162/email-fulfilment',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8162/email-fulfilment', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','http://localhost:8162/email-fulfilment', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("http://localhost:8162/email-fulfilment");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8162/email-fulfilment", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /email-fulfilment

Email Fulfilment Request

Body parameter

{
  "header": {
    "channel": "RH",
    "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
    "originatingUser": "fred.bloggs@ons.gov.uk",
    "source": "Survey Enquiry Line API"
  },
  "payload": {
    "emailFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "email": "example@example.com",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "uacMetadata": null
    },
    "smsFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "phoneNumber": "+447123456789",
      "uacMetadata": null
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	RequestDTO	true	none

Example responses

200 Response

{
  "qid": "string",
  "uacHash": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Send an email fulfilment for a case. Returns uacHash & QID if template has UAC/QID, or empty response if not	EmailFulfilmentResponseSuccess
400	Bad Request	Email Fulfilment request failed validation	EmailFulfilmentResponseError
500	Internal Server Error	Error with Gov Notify when attempting to send email	None

sms-fulfilment-endpoint

smsFulfilment

Code samples

# You can also use wget
curl -X POST http://localhost:8162/sms-fulfilment \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST http://localhost:8162/sms-fulfilment HTTP/1.1
Host: localhost:8162
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "header": {
    "channel": "RH",
    "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
    "originatingUser": "fred.bloggs@ons.gov.uk",
    "source": "Survey Enquiry Line API"
  },
  "payload": {
    "emailFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "email": "example@example.com",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "uacMetadata": null
    },
    "smsFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "phoneNumber": "+447123456789",
      "uacMetadata": null
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('http://localhost:8162/sms-fulfilment',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post 'http://localhost:8162/sms-fulfilment',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('http://localhost:8162/sms-fulfilment', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','http://localhost:8162/sms-fulfilment', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("http://localhost:8162/sms-fulfilment");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "http://localhost:8162/sms-fulfilment", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /sms-fulfilment

SMS Fulfilment Request

Body parameter

{
  "header": {
    "channel": "RH",
    "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
    "originatingUser": "fred.bloggs@ons.gov.uk",
    "source": "Survey Enquiry Line API"
  },
  "payload": {
    "emailFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "email": "example@example.com",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "uacMetadata": null
    },
    "smsFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "phoneNumber": "+447123456789",
      "uacMetadata": null
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	RequestDTO	true	none

Example responses

200 Response

{
  "qid": "string",
  "uacHash": "string"
}

Responses

Status	Meaning	Description	Schema
200	OK	Send an SMS fulfilment for a case. Returns uacHash & QID if template has UAC/QID, or empty response if not	SmsFulfilmentResponseSuccess
400	Bad Request	SMS Fulfilment request failed validation	SmsFulfilmentResponseError
500	Internal Server Error	Error with Gov Notify when attempting to send SMS	None

Schemas

EmailFulfilment

{
  "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  "email": "example@example.com",
  "packCode": "string",
  "personalisation": {
    "name": "Joe Bloggs"
  },
  "uacMetadata": null
}

Properties

Name	Type	Required	Restrictions	Description
caseId	string(uuid)	false	none	The case, which must exist in RM
email	string	false	none	The target email address, to which we will send a fulfilment
packCode	string	false	none	The pack code, which must exist in RM and the pack code must be allowed on the survey the case belongs to
personalisation	object,null	false	none	Optional personalisation key/value pairs to include in the sent email. Keys must match __request__. prefixed fields in the selected template, or they will be ignored
» additionalProperties	string	false	none	none
uacMetadata	any	false	none	Metadata for UACQIDLinks

EmailFulfilmentResponseError

{
  "error": "string"
}

Properties

Name	Type	Required	Restrictions	Description
error	string	false	none	none

EmailFulfilmentResponseSuccess

{
  "qid": "string",
  "uacHash": "string"
}

Properties

Name	Type	Required	Restrictions	Description
qid	string	false	none	none
uacHash	string	false	none	none

RequestDTO

{
  "header": {
    "channel": "RH",
    "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
    "originatingUser": "fred.bloggs@ons.gov.uk",
    "source": "Survey Enquiry Line API"
  },
  "payload": {
    "emailFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "email": "example@example.com",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "uacMetadata": null
    },
    "smsFulfilment": {
      "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
      "packCode": "string",
      "personalisation": {
        "name": "Joe Bloggs"
      },
      "phoneNumber": "+447123456789",
      "uacMetadata": null
    }
  }
}

Properties

Name	Type	Required	Restrictions	Description
header	RequestHeaderDTO	false	none	none
payload	RequestPayloadDTO	false	none	none

RequestHeaderDTO

{
  "channel": "RH",
  "correlationId": "48fb4cd3-2ef6-4479-bea1-7c92721b988c",
  "originatingUser": "fred.bloggs@ons.gov.uk",
  "source": "Survey Enquiry Line API"
}

Properties

Name	Type	Required	Restrictions	Description
channel	string	false	none	The product that is calling the API
correlationId	string(uuid)	false	none	The ID that connects all the way from the public web load balancer to the backend, and back again
originatingUser	string	false	none	The ONS user who is triggering this API request via an internal UI
source	string	false	none	The microservice that is calling the API

RequestPayloadDTO

{
  "emailFulfilment": {
    "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
    "email": "example@example.com",
    "packCode": "string",
    "personalisation": {
      "name": "Joe Bloggs"
    },
    "uacMetadata": null
  },
  "smsFulfilment": {
    "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
    "packCode": "string",
    "personalisation": {
      "name": "Joe Bloggs"
    },
    "phoneNumber": "+447123456789",
    "uacMetadata": null
  }
}

Properties

Name	Type	Required	Restrictions	Description
emailFulfilment	EmailFulfilment	false	none	none
smsFulfilment	SmsFulfilment	false	none	none

SmsFulfilment

{
  "caseId": "af51d69f-996a-4891-a745-aadfcdec225a",
  "packCode": "string",
  "personalisation": {
    "name": "Joe Bloggs"
  },
  "phoneNumber": "+447123456789",
  "uacMetadata": null
}

Properties

Name	Type	Required	Restrictions	Description
caseId	string(uuid)	false	none	The case, which must exist in RM
packCode	string	false	none	The pack code, which must exist in RM and the pack code must be allowed on the survey the case belongs to
personalisation	object,null	false	none	Optional personalisation key/value pairs to include in the sent email. Keys must match __request__. prefixed fields in the selected template, or they will be ignored
» additionalProperties	string	false	none	none
phoneNumber	string	false	none	The phone number, which must be a UK number consisting of 9 digits, preceded by a 7 and optionally a UK country code or zero (0, 044 or +44).
uacMetadata	any	false	none	Metadata for UACQIDLinks

SmsFulfilmentResponseError

{
  "error": "string"
}

Properties

Name	Type	Required	Restrictions	Description
error	string	false	none	none

SmsFulfilmentResponseSuccess

{
  "qid": "string",
  "uacHash": "string"
}

Properties

Name	Type	Required	Restrictions	Description
qid	string	false	none	none
uacHash	string	false	none	none