Retrieve contact

Browse API reference

GET/contacts/{contactId}getContact

Use this method to retrieve details about a contact.

To retrieve a contact, you need its contactId. Our gateway returned the contactId in the Create Processing Account method.

Note: If you don't have the contactId, use the List Contacts method to search for the contact.

Our gateway returns the following information about a contact:

Name and contact method, including their phone number or mobile number.
Role within the business, for example, if they are a manager.

Parameters

Name	In	Type	Description
`contactId`Required	path	`integer`	Unique identifier for the contact.

Responses

Successful request. Returns the requested contact.

200 OK · application/json

{
  "contactId": 1543,
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    },
    {
      "type": "phone",
      "value": "2025550164"
    },
    {
      "type": "mobile",
      "value": "8445557624"
    },
    {
      "type": "fax",
      "value": "2025550110"
    }
  ],
  "firstName": "Jane",
  "identifiers": [
    {
      "type": "nationalId",
      "value": "xxxxx4320"
    }
  ],
  "lastName": "Doe",
  "middleName": "Helen",
  "type": "manager"
}

Response schema · 21 fields

contactIdinteger
Unique identifier of the contact.
contactMethodsobject[]required
Array of polymorphic objects, which contain contact information. Note: If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number1–4 items
- emailobject
  - typestringrequired
    Type of contact method.email
  - valuestringrequired
    Email address.≤ 50 chars
- phoneobject
  - typestringrequired
    Type of contact method.phone
  - valuestringrequired
    Phone number.≤ 15 chars
- mobileobject
  - typestringrequired
    Type of contact method.mobile
  - valuestringrequired
    Mobile number.≤ 15 chars
- faxobject
  - typestringrequired
    Type of contact method.fax
  - valuestringrequired
    Fax number.≤ 15 chars
firstNamestringrequired
Contact's first name.≤ 50 chars
identifiersobject[]
Array of identifier objects.≥ 1 items
- typestringrequired
  Type of ID provided to verify identity.nationalId
- valuestringrequired
  Social Security Number (SSN) or Social Insurance Number (SIN).
lastNamestringrequired
Contact's last name.≤ 50 chars
middleNamestring
Contact's middle name.≤ 50 chars
typestringrequired
Type of contact.managerrepresentativeothers

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

delete-a-contact update-a-contact