Dispute Assignees¶

The assignee is the person at the tenant currently responsible for working a dispute. An assignee belongs to one or more departments. Assignees can be linked to an existing Billtrust Platform user by supplying a valid userId during create or update.

Retrieving an Assignee by ID¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/get_v1_tenants__tenantId__assignees__assigneeId_

Permission¶

Dispute Configuration : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/{assigneeId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeAssigneeV1Response.

Retrieving an Assignee by Email¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/get_v1_tenants__tenantId__assignees_by_email__assigneeEmail_

Permission¶

Dispute Configuration : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/by-email/{assigneeEmail}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeAssigneeV1Response.

Retrieving the Current User's Assignee¶

Returns the assignee record linked to the currently authenticated user. The user is derived from the auth token, no user ID parameter is needed.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/get_v1_tenants__tenantId__assignees_current_user

Permission¶

Dispute Configuration : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/current-user' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Example Response¶

See DisputeAssigneeV1Response.

Retrieving a List of Assignees¶

Returns all assignees for the tenant, optionally filtered by department. This endpoint has no pagination, all matching records are returned in a single response.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/get_v1_tenants__tenantId__assignees

Permission¶

Dispute Configuration : READ

Example Request¶

curl -X GET 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees?DepartmentId={departmentId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Query Parameters¶

Field	Type	Description
`DepartmentId`	string	Filter to assignees belonging to this department. Full match only

Example Response¶

See Dispute Assignee List.

Creating an Assignee¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/post_v1_tenants__tenantId__assignees

Permission¶

Dispute Configuration : CREATE

Example Request¶

curl -X POST 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

{
  "departmentId": "{departmentId}",
  "active": true,
  "allUpdates": true,
  "dailyDigest": false,
  "isDefault": false,
  "person": {
    "firstName": "Steve",
    "lastName": "Rogers",
    "email": "steve.rogers@avengers.com",
    "language": "en",
    "timezone": "America/New York"
  }
}

Request Fields¶

See Shared Assignee Request Fields.

Behavior Notes¶

Either userId or person.email must be provided. If userId is provided, the person fields are auto-populated from the Billtrust User Service, you do not need to supply them manually.
Setting isDefault: true automatically sets isDefault: false on all other assignees in the same department.

Example Response¶

See DisputeAssigneeV1Response.

Updating an Assignee by ID¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/put_v1_tenants__tenantId__assignees__assigneeId_

Permission¶

Dispute Configuration : UPDATE

Example Request¶

curl -X PUT 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/{assigneeId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

{
  "departmentId": "{departmentId}",
  "active": true,
  "allUpdates": true,
  "dailyDigest": false,
  "isDefault": false,
  "person": {
    "firstName": "Steve",
    "lastName": "Rogers",
    "email": "steve.rogers@avengers.com",
    "language": "en",
    "timezone": "America/New York"
  }
}

Request Fields¶

See Shared Assignee Request Fields. Note: departmentCode is not accepted on this endpoint, use departmentId only.

Example Response¶

See DisputeAssigneeV1Response.

Updating an Assignee by Email¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/put_v1_tenants__tenantId__assignees_by_email__assigneeEmail_

Permission¶

Dispute Configuration : UPDATE

Example Request¶

curl -X PUT 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/by-email/{assigneeEmail}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>' \
    -d '<request body>'

Example Request Body¶

{
  "departmentId": "{departmentId}",
  "active": true,
  "allUpdates": true,
  "dailyDigest": false,
  "isDefault": false,
  "person": {
    "firstName": "Steve",
    "lastName": "Rogers",
    "email": "steve.rogers@avengers.com",
    "language": "en",
    "timezone": "America/New York"
  }
}

Request Fields¶

See Shared Assignee Request Fields. Unlike update by ID, this endpoint also accepts departmentCode as an alternative to departmentId.

Example Response¶

See DisputeAssigneeV1Response.

Deleting an Assignee by ID¶

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/delete_v1_tenants__tenantId__assignees__assigneeId_

Permission¶

Dispute Configuration : DELETE

Example Request¶

curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/assignees/{assigneeId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Deleting an Assignee by Email¶

Deletes the assignee associated with the given email address within a specific department.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Dispute%20Service%20v1#/DisputeAssigneeV1/delete_v1_tenants__tenantId__departments_by_code__departmentCode__assignees_by_email__assigneeEmail_

Permission¶

Dispute Configuration : DELETE

Example Request¶

curl -X DELETE 'https://arc-aegis.billtrust.com/dispute/v1/tenants/{tenantId}/departments/by-code/{departmentCode}/assignees/by-email/{assigneeEmail}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-Billtrust-Api-Key: <API key value>'

Appendix¶

Shared Assignee Request Fields¶

Accepted by Create, Update by ID, and Update by Email. See each endpoint for notes on field-level differences.

Field	Type	Required	Description
`departmentId`	string	No	Internal ID of the department
`departmentCode`	string	No	Code alternative to `departmentId`. Not accepted on Update by ID
`active`	boolean	No	Whether the assignee is active; defaults to `false`
`userId`	string	No	Billtrust Platform user ID to link to this assignee. Either `userId` or `person.email` must be provided
`allUpdates`	boolean	No	When `true`, the assignee receives a notification on every dispute update; defaults to `false`
`dailyDigest`	boolean	No	When `true`, the assignee receives a daily email summary of their assigned disputes; defaults to `false`
`isDefault`	boolean	No	When `true`, this assignee is the default for new disputes in their department. Setting this automatically clears `isDefault` on all other assignees in the same department
`person.firstName`	string	No	First name
`person.lastName`	string	No	Last name
`person.email`	string	No	Email address. Either `userId` or `person.email` must be provided
`person.officePhone`	string	No	Office phone number
`person.cellPhone`	string	No	Cell phone number
`person.fax`	string	No	Fax number
`person.title`	string	No	Job title
`person.language`	string	No	Language code (e.g. `en`)
`person.timezone`	string	No	Timezone (e.g. `America/New York`)
`person.address.address1`	string	No	Street address line 1
`person.address.address2`	string	No	Street address line 2
`person.address.city`	string	No	City
`person.address.state`	string	No	State
`person.address.zip`	string	No	Postal code
`person.address.country`	string	No	Country code

DisputeAssigneeV1Response¶

Returned by single-assignee endpoints (Get by ID, Get by Email, Get Current User, Create, Update).

{
  "id": "{assigneeId}",
  "createUser": "{userId}",
  "createDate": "2021-03-27T18:50:05.300Z",
  "updateUser": "{userId}",
  "updateDate": "2021-03-27T18:50:05.300Z",
  "assigneeId": "{assigneeId}",
  "departmentId": "{departmentId}",
  "active": true,
  "tenantId": "{tenantId}",
  "userId": "{assigneeUserId}",
  "allUpdates": true,
  "dailyDigest": true,
  "isDefault": false,
  "person": {
    "firstName": "Steve",
    "lastName": "Rogers",
    "email": "steve.rogers@avengers.com",
    "officePhone": "13334445555",
    "cellPhone": "13334445555",
    "fax": null,
    "title": "Captain",
    "address": {
      "address1": "100 Broadway",
      "address2": null,
      "city": "New York",
      "state": "NY",
      "zip": "11234",
      "country": "US"
    },
    "language": "en",
    "timezone": "America/New York"
  }
}

Dispute Assignee List¶

Returned by Retrieving a List of Assignees. An array of DisputeAssigneeV1Responses.

[
  {
    "id": "{assigneeId}",
    "createUser": "{userId}",
    "createDate": "2021-03-27T18:50:05.300Z",
    "updateUser": "{userId}",
    "updateDate": "2021-03-27T18:50:05.300Z",
    "assigneeId": "{assigneeId}",
    "departmentId": "{departmentId}",
    "active": true,
    "tenantId": "{tenantId}",
    "userId": "{assigneeUserId}",
    "allUpdates": true,
    "dailyDigest": true,
    "isDefault": false,
    "person": {
      "firstName": "Steve",
      "lastName": "Rogers",
      "email": "steve.rogers@avengers.com",
      "officePhone": "13334445555",
      "cellPhone": "13334445555",
      "fax": null,
      "title": "Captain",
      "address": {
        "address1": "100 Broadway",
        "address2": null,
        "city": "New York",
        "state": "NY",
        "zip": "11234",
        "country": "US"
      },
      "language": "en",
      "timezone": "America/New York"
    }
  },
  ...
]