☰
Navigation :

Bureau Job Operations

Bureau Job Operations

There are several operations that can be used to build reusable Bureau Jobs and use them to create Submissions that can be sent to BACS or FPS.

Base URLs

There are two URLs that used, for development, it is recommeded that the Test URL is used. These URLs are:

This tutorial will use the test URL.

A complete list of operations can be found on the API document:

https://api.paygateservicedemo.com/bureau_publicapi/api/docs/index.html?url=/bureau_publicapi/api/docs/v1/swagger.json

Get Jobs

A HTTP GET request to the URL specified below will return a collection of available jobs for the requesting user.

HTTP GET
/bureau-jobs/

Example Response:

{
  "jobs": [
    {
      "jobName": "My Job",
      "groupId": "501179b2-1724-4ffa-a148-511bd3c2f78c",
      "groupName": "My Submission Group",
      "lastRun": "2019-08-24T14:15:22Z",
      "createdDate": "2019-08-24T14:15:22Z",
      "modifiedDate": "2019-08-24T14:15:22Z",
      "modifiedBy": "MalcomTucker",
      "deleteSourceFiles": false,
      "jobId": "1a90a17d-9bf0-46ec-80f7-604622f24bb0",
      "detailCount": 10,
      "jobUrl": "/api/v1/bureau-jobs/1a90a17d-9bf0-46ec-80f7-604622f24bb0"
    }
  ]  
}

Creates Job

Bureau Jobs can be created by performing a HTTP POST request to the endpoint below, with a Job Name, the Group Id and whether or not the source files for the Job require deletion following a successful submission.

HTTP POST
/bureau-jobs/

Example Request:

{
  "name": "Submission Job 2",
  "deleteSourceFiles": false,
  "groupId": "e45a26c0-9c46-457f-961d-9eafc249e380"
}

The response generated by the Create Job request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation, also inclded are IDs and URLs for the associated Job.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/"
}

Update Job

Jobs can be updated by performing a HTTP PUT request to the URL below. Jobs that are currently being used in a Submission may not be edited.

HTTP PUT
/bureau-jobs/

Example Request:

{
  "jobId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "name": "New Job Name",
  "deleteSourceFiles": true,
  "groupId": "e45a26c0-9c46-457f-961d-9eafc249e380"
}

The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation, also inclded are IDs and URLs for the associated Job.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/"
}

Get Job

Using a known Job ID, a HTTP GET request to the URL below will return the data for the specified Job.

HTTP GET
/bureau-jobs/{JOB-ID}

Example Response:

{
  "jobName": "My Job",
  "groupId": "501179b2-1724-4ffa-a148-511bd3c2f78c",
  "groupName": "My Submission Group",
  "lastRun": "2019-08-24T14:15:22Z",
  "createdDate": "2019-08-24T14:15:22Z",
  "modifiedDate": "2019-08-24T14:15:22Z",
  "modifiedBy": "MalcomTucker",
  "deleteSourceFiles": false,
  "jobId": "1a90a17d-9bf0-46ec-80f7-604622f24bb0",
  "detailCount": 10,
  "jobUrl": "/api/v1/bureau-jobs/1a90a17d-9bf0-46ec-80f7-604622f24bb0",
  "getDetails": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs"
}

Delete Job

Jobs that are not currently being used in a Submission may be deleted by performing a DELETE request to the endpoint below:

HTTP DELETE
/bureau-jobs/?jobId={JOB-ID}

The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Get Job Details

Using the Job ID, performing a HTTP GET request to hte URL below will return a collection of Job Details that are associated with that Job.

HTTP GET
/bureau-jobs/{JOB-ID}/details

Example Response

{
  "details": [
    {
      "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
      "customerName": "John Smith Business",      
      "customerReference": "JOHSMI0123123",
      "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "fileName": "Filename.txt",
      "importSchema": "Mapping",
      "mapping": "Your Mapping",
      "mappingId": "61dd8e3623efc80010824e09",
      "createdDate": "2019-08-24T14:15:22Z",
      "modifiedDate": "2019-08-24T14:15:22Z",
      "createdBy": "Malcom Tucker",
      "modifiedBy": "Terri Coverley",
      "jobDetailId": "8aedef92-2d3d-4570-b346-44ebad6f1a80",
      "url": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/details/8aedef92-2d3d-4570-b346-44ebad6f1a80"
    }
  ],
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/"
}

Add Job Detail

Job Details may be added to Bureau Jobs that are currently not being used in a submission by performing a POST request to the URL below. The Import Schema can be either Legacy, Standard 18 or Mapping. If an import schema of “Mapping” is used, a mapping id must be provided. The Customer Reference must exist in the system, and belong to the user performing the operation, and is mandatory if an import schema of “Mapping” or “Legacy” is used:

HTTP POST
/bureau-jobs/add-detail

Example Request:

{
  "jobId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "importSchema": "Standard18",
  "mappingId": "",
  "fileName": "MyFile*.txt",
  "customerReference": "IMPORTCUST"
}

The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation, also inclded are IDs and URLs for the associated Job and Job Detail.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/",
  "jobDetailId": "8aedef92-2d3d-4570-b346-44ebad6f1a80",
  "jobDetailUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/details/8aedef92-2d3d-4570-b346-44ebad6f1a80"
}

Get Job Detail

Performing a HTTP GET request to the URL below will return data for the specified Job Detail, including File Name, Import Schema.

HTTP GET
/bureau-jobs/{JOB-ID}/details/{DETAIL-ID}

Example Response:

{
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "customerName": "John Smith Business",
  "customerReference": "JOHSMI0123123",
  "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
  "fileName": "Filename.txt",
  "importSchema": "Mapping",
  "mapping": "Your Mapping",
  "mappingId": "61dd8e3623efc80010824e09",
  "createdDate": "2019-08-24T14:15:22Z",
  "modifiedDate": "2019-08-24T14:15:22Z",
  "createdBy": "Malcom Tucker",
  "modifiedBy": "Terri Coverley",
  "jobDetailId": "8aedef92-2d3d-4570-b346-44ebad6f1a80",
  "url": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/details/8aedef92-2d3d-4570-b346-44ebad6f1a80"
}

Update Job Detail

Job Details can be updated by performing a HTTP PUT request to the URL below. Jobs that are currently being used in a Submission may not be edited. The Import Schema can be either Legacy, Standard 18 or Mapping. If an import schema of “Mapping” is used, a mapping id must be provided. The Customer Reference must exist in the system, and belong to the user performing the operation, and is mandatory if an import schema of “Mapping” or “Legacy” is used:

HTTP PUT
/bureau-jobs/update-detail

Example Request:

{
  "jobId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "jobDetailId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "importSchema": "Mapping",
  "mappingId": "61dd8e3623efc80010824e09",
  "fileName": "SubmissionFile*.txt",
  "customerReference": "MONTHLYCUSTR01"
}

The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation, also inclded are IDs and URLs for the associated Job and Job Detail.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "jobId": "2b12c0b1-daa1-4c8a-b810-8913b9d85353",
  "jobUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/",
  "jobDetailId": "8aedef92-2d3d-4570-b346-44ebad6f1a80",
  "jobDetailUrl": "/api/v1/bureau-jobs/2b12c0b1-daa1-4c8a-b810-8913b9d85353/details/8aedef92-2d3d-4570-b346-44ebad6f1a80"
}

Delete Job Detail

Job Details can be removed from a Job by performing a HTTP DELETE request to the URL below. Jobs that are currently being used in a Submission may not be edited or deleted:

HTTP DELETE
/bureau-jobs/delete-job-detail?jobId={JOB-ID}&detailId={JOB-DETAIL-ID}

The response generated by the DELETE request will contain a boolean indicating success, as well as any messages generated by the operation, including around validation.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ]
}

Create Submission From Job

Once a Job has been created, and has one or more Job Details associated with it, it can be used to create a Bureau Submission. Performing a HTTP POST request to the endpoint below will create a Submission that may then be edited, validated and then submitted. A callback URL can be specified to post data back to a specified endpoint upon completion.

HTTP POST
/bureau-jobs/create-submission

Exmaple Request:

{
  "submissionReference": "MONTHLYSUB01",
  "contraNarrative": "CONTRA",
  "paymentDate": "2024/08/20",
  "jobId": "0e73ba95-8b81-480a-89e9-2350cb7bcbe1",
  "callBackUrl": ""
}

In the response are the Submission ID and the Submission URL, as well as a boolean value indicating success, and any messages generated by the API call. The Submission URL can then be used in a HTTP GET request to get details about the submission. An endpoint is included in the response that provides a task progress url that can be queried to establish if the job is complete and ready for to be edited or submitted.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissionId": "ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "submissionUrl": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
  "taskProgressUrl": "/api/v1/bureau-jobs/bureau-job-progress?submissionId=ed797670-6a5e-48ca-a9f8-c1011705dc9f"
}

Get Bureau Job Progress

Performing a HTTP GET request to the below endpoint will return progress percentages for the parts of the Job running process which in order are:

There is also a boolean value indicating success

HTTP GET
/bureau-jobs/bureau-job-progress?submissionId={SUBMISSION-ID}

The response contains percentage values on progression of each stage, a boolean value indicating success, submission ID and a URL for the submission for use within the API, also included is an array of messages relevant to the import, and a boolean value indicating if an error has occurred.

Example Response:

{
	"complete": true,
	"error": false,
	"messages": [
		"TenOneHundred0.csv: Imported 100 record(s)",
		"TenOneHundred1.csv: Imported 100 record(s)",
		"TenOneHundred2.csv: Imported 100 record(s)"
	],
	"importPercentage": 100,
	"processPercentage": 100,
	"validationPercentage": 100,
	"submissionId": "b9a3116f-e4ea-45bb-8c8a-39e2ed2e0380",
	"submissionUrl": "/api/v1/bureau-jobs/bureau-job-progress?submissionId=b9a3116f-e4ea-45bb-8c8a-39e2ed2e0380"
}

Get Job Bureau Customers

The Bureau Customers associated with a Job can be queried using the below endpoint:

HTTP GET
/bureau-jobs/{JOB-ID}/bureau-customers

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "customers": [
    {
      "name": "John Smith Business",
      "contactFirstName": "John",
      "contactSurname": "Smith",
      "customerAddress": {
        "line1": "15 High Street",
        "line2": "Fictional Business Park",
        "line3": "Fictional Area",
        "line4": "Fictional Area",
        "locality": "Fictional Locality",
        "postcode": "AA1 1AA",
        "town": "Fake Town",
        "county": "Fake County"
      },
      "telephone": "01234 567890",
      "telephone2": "01234 567890",
      "websiteUrl": "https://www.johnsmithsbusiness.fake/",
      "emailAddress": "johnsmith@johnsmithsbusiness.fake",
      "serviceUserNumber": "100000",
      "paymentLimit": 10,
      "submissionLimit": 10.5,
      "deleted": false,
      "contraNarrative": "CONTRA",
      "bankName": "Trusted Bank Plc.",
      "sortCode": "101010",
      "accountNumber": "10101010",
      "createdDate": "2019-08-24T14:15:22Z",
      "modifiedDate": "2019-08-24T14:15:22Z",
      "defaultImportSchema": "Mapping",
      "defaultImportMapping": "Your Mapping",
      "defaultImportFilename": "Filename.txt",
      "tags": "TAG1",
      "bankReference": "SMITH123",
      "bankAddress": {
        "line1": "15 High Street",
        "line2": "Fictional Business Park",
        "line3": "Fictional Area",
        "line4": "Fictional Area",
        "locality": "Fictional Locality",
        "postcode": "AA1 1AA",
        "town": "Fake Town",
        "county": "Fake County"
      },
      "customerId": "1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead",
      "reference": "YOURCUST001",
      "customerUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/",
      "notesUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/notes",
      "jobsUrl": "/api/v1/brueau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/jobs",
      "submissionsUrl": "/api/v1/bureau-customers/1b2bd9d9-c50d-4c5f-950c-bc62a8e20ead/submissions"
    }
  ]
}

Get Job Suns

It is possible to retrieve a list of Service User Numbers (SUNs) associated with a Bureau Job by querying the below endpoint. Each Customer may have a separate SUN:

HTTP GET
/bureau-jobs/{JOB-ID}/suns

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "suns": [
    "1234567",
    "2345678"
  ]
}

Get Job Submissions

It is possible to retrieve a list of Submissions associated with a Bureau Job by querying the below endpoint:

HTTP GET
/bureau-jobs/{JOB-ID}/submissions

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "submissions": [
    {
      "submissionId": "/api/v1/bureau-submissions/ed797670-6a5e-48ca-a9f8-c1011705dc9f",
      "submissionUrl": "string",
      "submissionReference": "MONTHLYSUB123",
      "job": "Monthly Job",
      "group": "My Submission Group",
      "created": "2019-08-24T14:15:22Z",
      "lastModification": "2019-08-24T14:15:22Z",
      "createdBy": "Malcom Tucker",
      "status": "Open",
      "locked": false,
      "editingUser": "Terri Coverley"
    }
  ]
}

Get Available Mappings

As well as the built in Import Schemas (Standard18 and Legacy) it is possible to pass the name of an existing Mapping in as the ImportSchema for the creation or updating of a Job Detail. A list of available mappings can be retrieved by querying the below endpoint.

HTTP GET
/bureau-jobs/mappings

Example Response:

[
  {
    "id": "string",
    "paygateId": "string",
    "title": "string"
  }
]

Get Available Files

Bureau Job Details are dependant on Files being picked up from directories in paygate, which may have been uploaded using paygate Agent. The files uploaded and the directories in use can be queried using the below endpoint:

HTTP GET
/bureau-jobs/files?filterText={OPTIONAL STRING TO MATCH}

The response generated by the Update request will contain a boolean indicating success, as well as any messages generated by the operation and a list of the directories and files that could be used as Job Details.

Example Response:

{
  "success": true,
  "messages": [
    "Operation Successful"
  ],
  "paths": [
    "string"
  ]
}