Get Terminal Assignment Details — API

Retrieves assignment history for a specified terminal using its terminalId UUID. Returns previous and new business unit and merchant details, assignment status, record creation timestamp, and creator information. Accessible to SUPER_ADMIN and PARTNER roles using API Key authentication through the X-API-KEY header.

1. Overview

The Get Terminal Assignment Details API retrieves the assignment history and details for a specified terminal. The response includes associated business units and merchants, assignment status, record creation timestamp, and the user who created each assignment record.

Access Levels: SUPER_ADMIN, PARTNER

2. Endpoint Details

PropertyValue
API NameGet Terminal Assignment Details
HTTP MethodGET
Endpoint/api/v1/tms/terminals/terminal/{terminalId}/terminal-assignment
Access LevelsSUPER_ADMIN, PARTNER
Request BodyNone
Success Response200 OK
Error Response400 Bad Request

3. Base URL

Production

https://app-api.edfapay.com

Full Endpoint

GET https://app-api.edfapay.com/api/v1/tms/terminals/terminal/{terminalId}/terminal-assignment

4. Authorization

This endpoint is available to the following access levels:

  • SUPER_ADMIN
  • PARTNER

Authentication uses an API key supplied through the X-API-KEY request header.

5. Path Parameters

ParameterTypeRequiredDescription
terminalIdUUIDYesUnique identifier of the terminal whose assignment details are requested.

Example

/api/v1/tms/terminals/terminal/3fa85f64-5717-4562-b3fc-2c963f66afa6/terminal-assignment

Replace the example UUID with the actual terminal ID.

6. Request Headers

HeaderValueDescription
X-API-KEYYOUR_API_KEYAuthenticates the API request.
Accept*/*Specifies the response media types accepted by the client.

No request body or query parameters are specified in the provided API definition.

7. cURL Example

curl --request GET \
  --url 'https://app-api.edfapay.com/api/v1/tms/terminals/terminal/TERMINAL_UUID/terminal-assignment' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Accept: */*'

Implementation notes:

  • Replace TERMINAL_UUID with the actual terminal UUID.
  • Replace YOUR_API_KEY with a valid API key.
  • This endpoint retrieves assignment records and does not perform an assignment.

8. Successful Response — 200 OK

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": [
    {
      "id": 0,
      "terminalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "oldBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "newBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "oldMerchantName": "string",
      "newMerchantName": "string",
      "oldMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "newMerchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdAt": "2026-10-28T12:09:28.375Z",
      "createdBy": "string",
      "assign": true
    }
  ]
}

The values shown are Swagger example placeholders and do not represent actual assignment records.

9. Response Fields

9.1 Top-Level Fields

FieldTypeDescription
codeNumberAPI response code.
messageStringResponse message.
errorCodeStringError identifier, if applicable.
dataArrayList of terminal assignment records.

9.2 Assignment Record — data[]

FieldTypeDescription
idNumberAssignment record identifier.
terminalIdUUIDTerminal identifier.
oldBusinessUnitIdUUIDPrevious business unit identifier.
newBusinessUnitIdUUIDNew business unit identifier.
oldMerchantNameStringPrevious merchant name.
newMerchantNameStringNew merchant name.
oldMerchantIdUUIDPrevious merchant identifier.
newMerchantIdUUIDNew merchant identifier.
createdAtString (date-time)Timestamp when the assignment record was created.
createdByStringUser or actor recorded as creating the assignment record.
assignBooleanIndicates whether the record represents an assignment (true) or an unassignment (false).

10. Error Response — 400 Bad Request

The endpoint documents 400 Bad Request as a possible response.

Example Response

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}
FieldTypeDescription
codeNumberAPI response code.
messageStringError or response message.
errorCodeStringError identifier.
dataObjectAdditional error details; empty in the documented example.

The values shown are Swagger example placeholders, not confirmed runtime response values.

11. Integration Workflow

  1. Authenticate using a valid API key and an authorized SUPER_ADMIN or PARTNER account.
  2. Obtain the UUID of the target terminal.
  3. Submit a GET request to the terminal assignment endpoint.
  4. Inspect the HTTP status and response payload.
  5. Iterate through the data array to review the returned assignment records.
  6. Compare the previous and new business unit or merchant fields where applicable.
  7. Use assign to identify whether each record represents an assignment or an unassignment.

12. Error Handling and Troubleshooting

If the API returns 400 Bad Request, consider checking the following:

  • Confirm that terminalId is supplied in the URL.
  • Verify that terminalId is a valid UUID.
  • Ensure that the request targets the intended environment.
  • Confirm that the X-API-KEY header contains a valid API key.
  • Inspect message and errorCode for additional diagnostic information.

These are general troubleshooting recommendations. The endpoint's exact validation rules and error mappings are not specified in the provided schema.

13. Important Considerations

  • The endpoint uses the GET method.
  • The required terminalId path parameter must be a UUID.
  • The documented access levels are SUPER_ADMIN and PARTNER.
  • Authentication uses the X-API-KEY header.
  • The response's data field is an array and can contain multiple assignment records.
  • Previous and new business unit and merchant fields can help identify changes in terminal assignment.
  • Sorting, pagination, and the complete set of possible assignment scenarios are not specified in the provided API definition.

Did this page help you?