Table of Contents

  1. Overview

    1. Collaborating with ServeManager Users
    2. Getting Started
    3. Authentication
    4. Content Type
    5. Enumerated Attributes
    6. Date Formatting
    7. Pagination
    8. Creating a new job
    9. Job ID Distinction
    10. Uploading Documents
    11. System Event Emails
  2. Troubleshooting

    1. Status Codes
  3. Resource Methods

    1. Account
    2. Employees
    3. Companies
    4. Court Cases
    5. Courts
    6. Jobs
    7. Uploads
    8. Notes
    9. Attempts
    10. Invoices
    11. Webhooks
  4. Webhooks

    1. Webhook Interface
    2. Batching
    3. Authenticating Requests
  5. Webhook Payloads

    1. Job Payload Events
    2. Note Payload Events

ServeManager API

Overview

Collaboration

Collaboration with other ServeManager users is the most common use case for the API, and something that you will likely want to take advantage of. Currently, collaboration must be setup within the app. This process is outlined in this article on collaboration. A directory of ServeManager users is available within the app and is a great resource for finding experienced ServeManager users to collaborate with in nearly every state and a few countries!

For instance, as a law firm with a high volume of jobs that require service of process, you could set up collaboration between process servers that are already using ServeManager to manage their jobs in all of the locations that service needs to occur in. Using the API, you could create jobs and assign them to the companies that service the area of the job. Status updates, attempts, notes, affidavits and invoices on those jobs could all be obtained from the API and that data used to update your internal systems.

Contact us to set up a collaboration account for you for testing your client.

Building a Client

In order to build a basic client for the ServeManager API, three main concepts are required.

  1. Authentication
  2. GET an existing resource
  3. POST (create) a resource

Our recommendation is to start build your client code in that order. Once you have mastered each, you can reapply the the code and concepts to the other API endpoints you need.

Check out our basic ruby client example code to see how we approached this process. We only worried about getting the correct response status from the API for each concept. If you've got the right status code from the API for all three concepts, you can move on to decoding the JSON response and adding the business logic for your app.

You can build your library with any language and access the API from any platform you prefer. Ruby is not required.

Design of the API

The API is designed to expose easily understandable URLs and to use HTTP response codes to indicate request status and errors. The ServeManager API is RESTful and response bodies are JSON.

Examples requests are shown using the command line utility curl, which is not required for accessing the API in any way. It's a simple way of demonstrating resource URLs, expected headers and data payloads. We would recommend using an alternative for production.

Authentication

If you are an account owner, create an API key by visiting the API Keys page. Keep your API key secret. Never email or send the key in plain text.

SSL is required for all requests, and every endpoint has the base URL https://www.servemanager.com/. HTTP Basic Authentication is used to identify your account with an API key.

Your API key is the username in the HTTP Basic Authentication header, the password should remain empty. In the curl examples that follow, replace ${API_KEY} with the key from your account settings. The colon after ${API_KEY} in the examples is the username:password delimiter. ${API_KEY} is the username, password empty. \ characters in the examples are used to split the arguments to newlines in the shell for easier reading.

curl https://www.servemanager.com/api/account \
  -u ${API_KEY}: \

You may need to base64 encode the Authorization header value if your web request library does not. In this .NET/C# basic example the userName variable is your API key, and userPassword variable should be an empty string.

Content Type

JSON is the only supported content type for POST, PUT, PATCH, GET methods.

HTTP header Content-Type: application/json must be set when performing a POST, PUT, PATCH method. The body of the request must be JSON-encoded. Requests that don't fulfill these requirements will be rejected with HTTP status 406.

Enumerated Attributes

A number of endpoints contain enumerated attributes, and will return or accept a single value from a number of options. Some of these enumerated attributes support custom values (Any arbitrary value you desire). Sending an unsupported value in a POST, PUT, PATCH endpoint will still succeed, but editing that company from within the servemanager application may not display the unsupported value properly. Endpoints that support enumerated values will be indicated below, with a list of their accepted values.

Date Formatting

A number of attributes in the API are dates or datetimes. Whether using GET to access a date, or creating/updating a resource's date, the format should always match the ISO 8601 date format standard.

Date example: 2013-02-27

Date with time example: 2013-02-27T15:18:23-04:00

Pagination

All index API endpoints support pagination. Pagination links will be available in the top-level of the JSON response

Example:

"links":{
  "self":"https://www.servemanager.com/api/employees?page=1",
  "first":"https://www.servemanager.com/api/employees?page=1",
  "last":"https://www.servemanager.com/api/employees?page=3",
  "prev":null,
  "next":"https://www.servemanager.com/api/employees?page=2"
}

If multiple pages exist, either the "prev" or "next" attributes will contain endpoint URLs to request additional records. Requesting a page beyond the last one (In this example, if you requested the endpoint with a page=4 URL parameter), an empty data object will be returned.

Creating a new job

When creating a new job, you should first determine which associated objects you want on the job by either creating them, or using an id. Associations you will want to know before hand are: Client Company, Client Contact, Process Server Company, Process Server Contact, Employee Process Server, Court Case (Which itself requires a Court Location).

If any of these objects are absent or unknown when you create the job, you can omit the ids entirely.

For example, to create a new job with a client company/contact, you would first need to create a new company (or use a company_id that you already know), and then create the job.

ServeManager Job ID Distinction

When displaying ServeManager Job IDs to users, always use job.servemanager_job_number.

job.idis for your internal system reference only and should never be presented to a user. This is a source of confusion because the ServeManager UI and users use the phrase "Job ID" to reference jobs. They are actually referring to. job.servemanager_job_number behind the scenes. Currently job.servemanager_job_number is system-generated and not able to be user-defined.

Uploading Documents

ServeManager distinguishes between two types of uploads: documents to be served and miscellaneous attachments. Documents to be served is intended only for service documents. Miscellaneous attachments should be used for ancillary documents such as photos of a recipient.

There are two different ways to handle file uploads:

Attaching a file from an external URL

If you provide the external_url parameter within the attachment attributes, as shown in the job create: documents_to_be_served_attributes endpoint parameters, ServeManager will automatically seek out the file from that URL, download it, and attach it to the job for you. No other action is needed for that file to get attached, besides making sure it is accessible at the provided URL.

Uploading a local file

The upload process involves two steps. First, include meta data about the documents in the

on the job create endpoint.

Second, the job response will contain a publicly accessible URL: put_url (see the document upload example). This URL is a short-lived, publicly-accessible URL. Use it only for a single document upload as it will expire shortly after a job create event. Therefore, uploads should be done immediately after a job is created to ensure web requests are not blocked by long-running uploads.

Reference Number

The reference_number is a unique identifier for the document that can be created by the user. It is used to identify specific attachments in payloads without having to rely on file name.

System Event Emails

There are a number of emails that are sent on the user's behalf when performing certain actions within ServeManager. When using the API to perform these actions the system WILL NOT send an email on the user's behalf.

Troubleshooting

Some solutions to common problems encountered when getting started with the API.

Status Codes

200 - Success
201 - Created
401 - Unauthorized (API key not recognized. Ensure API key is HTTP Auth username, password empty, and value is base64 encoded)
403 - Forbidden (API key recognized, but some other permission is preventing you from using this request - see errors in response for details)
406 - Not Acceptable (ensure HTTP header "Content-Type: application/json" )
422 - Invalid Request (validation errors, see errors in response)
409 - Conflict (See errors in response)
500 - Server Error

Resource Methods

Account

Enumerated Account Attributes:

Attribute name Default values Supports custom value?
data['addresses']['label'] "", Company", "Corporate", "Branch", "Home" Yes

GET /api/account

Returns information about your account.

Example Request:

curl https://www.servemanager.com/api/account \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "type": "account",
    "links": {
      "self": "https://www.servemanager.com/api/account"
    },
    "id": 100523,
    "company_name": "Acme Incorporated",
    "phone": "800-555-8275",
    "fax": "",
    "email": "[email protected]",
    "website": "www.example.com",
    "monthly_jobs_quota": 300,
    "month_job_count": 96,
    "created_at": "2015-01-11T06:52:25-05:00",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "addresses": [
      {
        "type": "address",
        "id": 195238,
        "label": "Company",
        "address1": "555 Example Street",
        "address2": "Suite 542",
        "city": "Denver",
        "state": "CO",
        "postal_code": "80234",
        "county": "Adams County",
        "lat": 24.923,
        "lng": -51.888,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      }
    ]
  }
}

Employees

GET /api/employees

Returns a list of your accounts' employees, some details about them, and their permission level

Pagination may be utilized here. Please see the Pagination section for more details.

Example Request:

curl https://www.servemanager.com/api/employees \
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/employees?page=1",
    "first": "https://www.servemanager.com/api/employees?page=1",
    "last": "https://www.servemanager.com/api/employees?page=1",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "type": "employee",
      "id": 101234,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "321-555-7777",
      "license_number": "BCD-2347",
      "permission": "owner",
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00"
    },
    {
      "type": "employee",
      "id": 101379,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "333-555-8729",
      "license_number": "BCD-8879",
      "permission": "limited",
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00"
    }
  ]
}

GET /api/employees/:id

Returns details about a specific employee

Example Request:
curl https://www.servemanager.com/api/employees/101234 \
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/employees/101234"
  },
  "data": [
    {
      "type": "employee",
      "id": 101234,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "321-555-7777",
      "license_number": "BCD-2347",
      "permission": "owner",
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00"
    },
  ]
}

Companies

Enumerated Company Attributes:

Attribute name Default values Supports custom value?
data['company_type'] "", Attorney", "Contractor", "Government", "Individual", "Law Firm", "Paralegal", "Process Server" Yes
data['phone_numbers']['label'] "Office", "Mobile", "Fax", "Pager", "Home", "Other" No
data['email_addresses']['label'] "Work", "Home", "General", "Other" No
data['addresses']['label'] "", Company", "Corporate", "Branch", "Home" Yes

GET /api/companies

Returns an array of companies and details about them.

Pagination may be utilized here. Please see the Pagination section for more details.

Available URL Parameter Filters:

The list of companies can be filtered down by providing various URL parameters.

Parameter Description Supported Values Example
q Perform a text search on companies and contacts. Most useful for finding a company by email address. Any value, full email address will be the most deterministic.
page Return a paginated page for the companies list. See the pagination section for details Any numerical value
filter[archive_state] List companies based on whether they have been archived or not. Only the values "all", "active", or "archived" will do anything. Omitting the parameter defaults to "active", and unknown values will be ignored.
filter[date_range][type] Filters a timestamp by date range. type is the name of the timestamp to filter by min and max specify the range. Timestamps available for filtering are "archived_at", "created_at", "updated_at"
filter[date_range][min] The min date for the date range filter Should be a date using a similar format to "2021-02-27T13:18:23-04:00" (ISO 8601 date format). Should be a date earlier than [max], [max] See filter[date_range][type] example
filter[date_range][max] The max date for the date range filter Formatted "2021-02-27T15:18:23-04:00". Should be a date later than [min], [min] See filter[date_range][type] example

Example Request:

curl https://www.servemanager.com/api/companies
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/companies?page=1",
    "first": "https://www.servemanager.com/api/companies?page=1",
    "last": "https://www.servemanager.com/api/companies?page=1",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "links": {
        "self": "https://www.servemanager.com/api/companies/155987"
      },
      "type": "company",
      "id": 155987,
      "name": "Example Law Firm Inc.",
      "website": "http://www.example.com",
      "company_type": "Law Firm",
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "collaborating": false,
      "collaboration_account_id": null,
      "private_note": "Covers Denver, CO",
      "phone_numbers": [
        {
          "type": "phone_number",
          "id": 188999,
          "label": "Office",
          "number": "789-555-1738",
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00"
        }
      ],
      "email_addresses": [
        {
          "type": "email_address",
          "id": 154888,
          "label": "Work",
          "email": "[email protected]",
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00"
        }
      ],
      "addresses": [
        {
          "type": "address",
          "id": 555879,
          "label": "Corporate",
          "address1": "888 Example Street",
          "address2": "",
          "city": "Los Angeles",
          "state": "CA",
          "postal_code": "55555",
          "county": null,
          "lat": 29.99999,
          "lng": -95.28374,
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "primary": true
        }
      ],
      "contacts": [
        {
          "id": 77777,
          "first_name": "John",
          "last_name": "Doe",
          "title": "Captain",
          "email": "[email protected]",
          "phone": "111-555-8729",
          "license_number": "CA15123",
          "license_expiration": "June, 2027",
          "dob": "05/12/1989",
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "primary": true
        }
      ]
    }
  ]
}

GET /api/companies/:id

Returns details about a single specific company.

Example Request:

curl https://www.servemanager.com/api/companies/155987 \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/companies/155987"
    },
    "type": "company",
    "id": 155987,
    "name": "Example Law Firm Inc.",
    "website": "http://www.example.com",
    "company_type": "Law Firm",
    "created_at": "2015-01-11T06:52:25-05:00",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "private_note": "Covers Denver, CO",
    "collaborating": false,
    "collaboration_account_id": null,
    "phone_numbers": [
      {
        "type": "phone_number",
        "id": 188999,
        "label": "Office",
        "number": "789-555-1738",
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00"
      }
    ],
    "email_addresses": [
      {
        "type": "email_address",
        "id": 154888,
        "label": "Work",
        "email": "[email protected]",
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00"
      }
    ],
    "addresses": [
      {
        "type": "address",
        "id": 555879,
        "label": "Corporate",
        "address1": "888 Example Street",
        "address2": "",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "55555",
        "county": null,
        "lat": 29.99999,
        "lng": -95.28374,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      }
    ],
    "contacts": [
      {
        "id": 77777,
        "first_name": "John",
        "last_name": "Doe",
        "title": "Captain",
        "email": "[email protected]",
        "phone": "111-555-8729",
        "license_number":"CA15123",
        "license_expiration":"June, 2027",
        "dob":"05/12/1989",
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      }
    ]
  }
}

POST /api/companies

Creates a new company with the specified attributes. Only name and type are required.

Attribute Description
type* MUST be equal to "company". Any other value here, or the absence of this attribute will result in an HTTP 409 CONFLICT error.
name* Name of the company
website
company_type Type of company - see Enumerated Companies Attributes above for supported values.
private_note Note about company for internal use
addresses_attributes

Must be an array of JSON address objects to be created. Example:

{
  "addresses_attributes": [
    {
      "label":"Branch",
      "address1":"555 Example Street",
      "city":"Denver",
      "state":"CO",
      "postal_code":"80221",
      "primary":true
    }
  ]
}
addresses_attributes['label'] Label of the address. See possible values above.
addresses_attributes['address1'] Address line 1
addresses_attributes['address2'] Address line 2
addresses_attributes['city']
addresses_attributes['state']
addresses_attributes['postal_code'] Zip code for address
addresses_attributes['primary'] true or false - primary address for the company
email_addresses_attributes

Must be an array of JSON email_address objects to be created. Example:

{
  "email_addresses_attributes": [
    {
      "label":"Work",
      "email":"[email protected]"
    }
  ]
}
email_addresses_attributes['label'] Label for the email address. See possible values above.
email_addresses_attributes['email'] The email address
phone_numbers_attributes

Must be an array of JSON phone_number objects to be created. Example:

{
  "phone_numbers_attributes": [
    {
      "label":"Office",
      "number":"222-555-8879"
    }
  ]
}
phone_numbers_attributes['label'] Label for the phone number. See possible values above.
phone_numbers_attributes['number'] The phone number
contacts_attributes

Must be an array of JSON contact objects to be created. Example:

{
  "contacts_attributes": [
    {
      "title":"",
      "first_name":"Bob",
      "last_name":"Smith",
      "phone":"876-555-1234",
      "email":"[email protected]",
      "license_number":"CO114423",
      "license_expiration":"May, 2030",
      "dob":"01/07/1980",
      "primary":true
    }
  ]
}
contacts_attributes['title'] Contact's title
contacts_attributes['first_name'] Contact's first name
contacts_attributes['last_name'] Contact's last name
contacts_attributes['phone'] Contact's phone number
contacts_attributes['email'] Contact's email address
contacts_attributes['license_number'] Contact's license number
contacts_attributes['license_expiration'] Contact's license expiration
contacts_attributes['dob'] Contact's date of birth
contacts_attributes['primary'] true or false - indicates if this is the primary contact for the company.

Example Request:

curl https://www.servemanager.com/api/companies \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"company","name":"Bob Process Serving","company_type":"Process Server"}}'

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/companies/294680"
    },
    "type": "company",
    "id": 294680,
    "name": "Bob Process Serving",
    "website": null,
    "company_type": "Process Server",
    "created_at": "2015-01-11T06:52:25-05:00",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "private_note": "",
    "collaborating": false,
    "collaboration_account_id": null,
    "phone_numbers": [

    ],
    "email_addresses": [

    ],
    "addresses": [
      {
        "type": "address",
        "id": 570959,
        "label": "",
        "address1": "550 Highland St",
        "address2": "Suite 215",
        "city": "Frederick",
        "state": "MD",
        "postal_code": "21701",
        "county": null,
        "lat": 39.4155889,
        "lng": -77.3911109,
        "created_at": "2015-03-13T08:18:08-04:00",
        "updated_at": "2015-03-13T08:18:08-04:00",
        "primary": true
      }
    ],
    "contacts": [
      {
        "id": 77777,
        "first_name": "John",
        "last_name": "Doe",
        "title": "Captain",
        "email": "[email protected]",
        "phone": "111-555-8729",
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      }
    ]
  }
}

PUT /api/companies/:id

Updates an existing company

Attributes allowed here are identical to those found in the companies create endpoint. All attributes are optional, and any included attributes will update the existing data on the company with the following exceptions:

Attribute Description
addresses_attributes Accepts the same format as the create endpoint, however any addresses included here will be added to the company. Existing addresses on the company will remain unchanged, and the API does not currently provide a way to remove addresses from a company.

Example Request:

curl https://www.servemanager.com/api/companies/1234 -X PUT \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"company","company_type":"Process Server","private_note":"Only serves 80202","addresses_attributes":[{"address1":"555 Yorkshire Ave","city":"Westminster","state":"CO"}]}}'

Court Cases

GET /api/court_cases

Returns an array of court cases on your account

Pagination may be utilized here. Please see the Pagination section for more details.

Available URL Parameter Filters:

The list of court cases can be filtered down by providing some URL parameters.

Parameter Description Supported Values Example
company_id Only list court cases associated with a specific company (Where the company is the process_server or client of jobs on the court case). Any valid, numerical id for an existing company
q Perform a text search for court cases that match the given value. Can match case numbers, plaintiff, defendant, and the court's branch_name. Any value whatsoever (note that you may need to URL-escape it)
page Return a paginated page for the court_case. See the pagination section for details Any numerical value
filter Filters court cases by specific criteria (options are explained below).
filter[archive_state] List court cases based on whether they have been archived or not. Only the values 'all', 'archived' or 'active' will do anything. Omitting the parameter defaults to 'active', and unknown values will be ignored.

Example Request:

curl 'https://www.servemanager.com/api/court_cases?q=ABC-123' \
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/court_cases?q=ABC-123",
    "first": "https://www.servemanager.com/api/court_cases?page=1&q=ABC-123",
    "last": "https://www.servemanager.com/api/court_cases?page=1&q=ABC-123",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "links": {
        "self": "https://www.servemanager.com/api/court_cases/111234"
      },
      "type": "court_case",
      "id": 111234,
      "plaintiff": "The Plaintiff",
      "defendant": "The Defendant",
      "filed_date": "2015-03-26",
      "court_date": "2015-05-12",
      "number": "ABC-123",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "court": {
        "links": {
          "self": "https://www.servemanager.com/api/courts/45261"
        },
        "type": "court",
        "id": 45261,
        "branch_name": "Circuit Court",
        "county": "Larimer County",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "default": false,
        "address": {
          "address1": "555 Example Street",
          "address2": null,
          "city": "Denver",
          "state": "CO",
          "postal_code": "80221"
        }
      }
    }
  ]
}

GET /api/court_cases/:id

Returns details about a single specific court case.

Example Request:

curl https://www.servemanager.com/api/court_cases/111234 \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/court_cases/111234"
    },
    "type": "court_case",
    "id": 111234,
    "plaintiff": "The Plaintiff",
    "defendant": "The Defendant",
    "filed_date": "2015-03-26",
    "court_date": "2015-05-12",
    "number": "ABC-123",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "court": {
      "links": {
        "self": "https://www.servemanager.com/api/courts/45261"
      },
      "type": "court",
      "id": 45261,
      "branch_name": "Circuit Court",
      "county": "Larimer County",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "default": false,
      "address": {
        "address1": "555 Example Street",
        "address2": null,
        "city": "Denver",
        "state": "CO",
        "postal_code": "80221"
      }
    }
  }
}

POST /api/court_cases

Creates a new court case with the specified attributes. Only type is required

Attribute Description
type * MUST be equal to "court_case". Any other values causes a 409 CONFLICT error.
plaintiff
defendant
filed_date A date (without timestamp). Should match the format defined under the Date Formatting section.
court_date A date (without timestamp). Should match the format defined under the Date Formatting section.
number The court case number
court_id The id of the court location. You can create or access court location ids using the Courts API

Example Request:

curl https://www.servemanager.com/api/court_cases \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"court_case", "plaintiff":"Michael Bluth"}}' \

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/court_cases/428808"
    },
    "type": "court_case",
    "id": 428808,
    "plaintiff": "Michael Bluth",
    "defendant": null,
    "filed_date": null,
    "court_date": null,
    "number": null,
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "court": null
  }
}

Courts

GET /api/courts

Returns an array of court locations on your account

Pagination may be utilized here. Please see the Pagination section for more details.

Example Request:

curl https://www.servemanager.com/api/courts \
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/courts?page=1",
    "first": "https://www.servemanager.com/api/courts?page=1",
    "last": "https://www.servemanager.com/api/courts?page=1",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "links": {
        "self": "https://www.servemanager.com/api/courts/45261"
      },
      "type": "court",
      "id": 45261,
      "branch_name": "Circuit Court",
      "county": "Larimer County",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "default": false,
      "address": {
        "address1": "555 Example Street",
        "address2": null,
        "city": "Denver",
        "state": "CO",
        "postal_code": "80221"
      }
    }
  ]
}

GET /api/courts/:id

Returns details about a single specific court location

Example Request:

curl https://www.servemanager.com/api/courts/46112 \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/courts/45261"
    },
    "type": "court",
    "id": 45261,
    "branch_name": "Circuit Court",
    "county": "Larimer County",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "default": false,
    "address": {
      "address1": "555 Example Street",
      "address2": null,
      "city": "Denver",
      "state": "CO",
      "postal_code": "80221"
    }
  }
}

POST /api/courts

Creates a new court location with the specified attributes. Only type is required

Attribute Description
type * MUST be equal to "court". Any other values causes a 409 CONFLICT error.
branch_name
county
default true or false boolean value that indicates whether or not this court will be the default on new jobs in the application.
address_attributes

A JSON object with attributes for the court's address. Example:

{
  "address_attributes": {
    "address1":"555 Example Street",
    "address2":"Suite 329",
    "city":"Denver",
    "state":"CO",
    "postal_code":"80221"
  }
}
address_attributes['address1'] Court address line 1 (street address)
address_attributes['address2'] Court address line 2 (apt, suite, etc)
address_attributes['city'] Court city
address_attributes['state'] Court state
address_attributes['postal_code'] Court postal code

Example Request:

curl https://www.servemanager.com/api/courts \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"court","branch_name":"Superior","address_attributes":{"city":"Los Angeles"}}}'

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/courts/49106"
    },
    "type": "court",
    "id": 49106,
    "branch_name": "Superior",
    "county": null,
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "default": false,
    "address": {
      "address1": null,
      "address2": null,
      "city": "Los Angeles",
      "state": null,
      "postal_code": null
    }
  }
}

Jobs

Enumerated Job Attributes:

Attribute name Default values Supports custom value?
data['job_status'] Any value is valid here, as the available job statuses are customizable for your account. The defaults that accounts start with are: "Canceled", "Filed", "On Hold", and "Skip Trace". Yes
data['recipient']['ethnicity'] "", "African American", "Asian American", "Caucasian", "Hispanic", "Latino", "Middle Eastern", "Native American", "Native Hawaiian", "Other" No
data['recipient']['gender'] "", "Male", "Female", "Other" No
data['recipient']['height1'] "", "3'", "4'", "5'", "6'", "7'", "8'", "9'" No
data['recipient']['height2'] '', '1"','2"','3"','4"','5"','6"','7"','8"','9"','10"','11"','12"' No
data['recipient']['hair'] "", "Bald", "Black", "Blond", "Brown", "Gray", "Red", "White", "Other" No
data['recipient']['eyes'] "", "Amber", "Black", "Blue", "Brown", "Gray", "Green", "Hazel", "Other" No
data['recipient']['relationship'] "", "Aunt", "Boyfriend", "Brother", "Cousin", "Daughter", "Father", "Girlfriend", "Grandfather", "Grandmother", "Husband", "Mother", "Partner", "Nephew", "Niece", "Sister", "Son", "Uncle", "Wife", "Other" Yes
data['addresses']['label'] "", Company", "Corporate", "Branch", "Home" Yes

GET /api/jobs

Returns an array of jobs available for you

Pagination may be utilized here. Please see the Pagination section for more details.

Available URL Parameter Filters:

The list of jobs can be filtered down by providing various URL parameters. Note that parameters with additional options may need to have their brackets [] URL-escaped as such: %5B for [, %5D for ]

Parameter Description Supported Values Example
court_case_id Only list jobs associated with a specific court_case Any valid, numerical id for an existing court_case
company_id Only list jobs where either the client, or the process_server is a specific company Any valid, numerical id for an existing company
q Perform a text search for jobs that match the given value. Can match company names, zip codes, recipients, and other job attributes Any value whatsoever (note that you may need to URL-escape it)
page Return a paginated page for the job. See the pagination section for details Any numerical value
filter Filters jobs by specific criteria (options are listed/explained below). Filter options that accept arrays will display jobs that match any of the given values. For example, sending "1", and "2" to the attempt_count filter will show all jobs with 1 or 2 attempts on them - but NOT jobs with 0, 3, or more than 3 attempts. On the other hand, different types of filters will only display those jobs that match all of the given filters. For example, requesting archive_state=archived and attempt_count=1 will show only those jobs that are both archived, and have exactly 1 attempt on them.
filter[archive_state] List jobs based on whether they have been archived or not. Only the values "all", "active", or "archived" will do anything. Omitting the parameter defaults to "active", and unknown values will be ignored.
filter[server] List jobs that have a specific employee_process_server selected. Any valid, numerical id for an existing employee on your account.
filter[affidavit_status][] An array of options that will filter jobs by whether or not an affidavit has been created and whether it has been signed. Only the values "none", "unsigned", and "signed" will do anything
filter[invoice_status][] An array of options that filters jobs by the status of their invoices Only the values "none", "draft", "issued", and "paid" will do anything
filter[attempt_count][] An array of options that filters jobs by the number of attempts made on those jobs. There are two formats of values accepted:
  • Any numerical value greater than or equal to 0
  • Any number >= 0 followed by the plus (+) sign. This will show jobs that have >= that number of attempts made. For example, 4+ will show jobs with 4 or more attempts. The plus symbol should be URL-escaped as %2B
filter[service_status][] An array of options that filters based on the service status You may send an empty value (which filters by jobs with NO service status), or any of the values "Attempted", "Non-Service", or "Served".
filter[job_status][] An array of options that filters by user-defined job statuses Any value is valid here, as the available job statuses are customizable for your account. The defaults that accounts start with are: "Canceled", "Filed", "On Hold", and "Skip Trace". Sending an empty value will filter by jobs with no job status set at all
filter[date_range][type] Filters a timestamp by date range. type is the name of the timestamp to filter by min and max specify the range. Timestamps available for filtering are "created_at", "served_at", "archived_at", "due_date", "filed_date", "court_date"
filter[date_range][min] The min date for the date range filter Should be a date using a similar format to "2013-02-27T13:18:23-04:00" (ISO 8601 date format). Should be a date earlier than [max], [max] See filter[date_range][type] example
filter[date_range][max] The max date for the date range filter Formatted "2013-02-27T15:18:23-04:00". Should be a date later than [min], [min] See filter[date_range][type] example
filter[service_level] Filters for rush or routine jobs The values "Rush" or "Routine" are allowed.
sort Returns the list of jobs in a specified sorting order. There are two sub-parameters, sort[type] and sort[direction].
sort[type] The attribute on jobs to sort by The following values for this parameter will change the sorting:
  • created_at Sorts by when the job was created
  • due_date Sorts by the due date on jobs
  • attempt_count Sorts by the number of attempts on the job
  • server_name Sorts by the process server name
  • job_status Sorts by the job's job_status, alphabetically
sort[direction] The direction to sort the jobs This can be either "desc" for descending, or "asc" for ascending. For alphabetical sorting, "asc" will sort "A-Z", for numerical sorting, "asc" will be from lowest number to highest number (IE: 0 to 999), for date sorting, "asc" will be from oldest to newest

Example Request:

curl 'https://www.servemanager.com/api/jobs?filter%5Barchive_state%5D=active&

filter%5Battempt_count%5D%5B%5D=3&


filter%5Battempt_count%5D%5B%5D=4%2B&


filter%5Bservice_status%5D%5B%5D=Served' \
-u ${API_KEY}:

Note that the above URL is using the URL with parameters:

https://www.servemanager.com/api/jobs?filter[archive_state]=active&filter[attempt_count][]=3&filter[attempt_count][]=4+&filter[service_status][]=Served

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/jobs?filter%5Barchive_state%5D=active&filter%5Battempt_count%5D%5B%5D=3&filter%5Battempt_count%5D%5B%5D=4%2B&filter%5Bservice_status%5D%5B%5D=Served",
    "first": "https://www.servemanager.com/api/jobs?filter%5Barchive_state%5D=active&filter%5Battempt_count%5D%5B%5D=3&filter%5Battempt_count%5D%5B%5D=4%2B&filter%5Bservice_status%5D%5B%5D=Served&page=1",
    "last": "https://www.servemanager.com/api/jobs?filter%5Barchive_state%5D=active&filter%5Battempt_count%5D%5B%5D=3&filter%5Battempt_count%5D%5B%5D=4%2B&filter%5Bservice_status%5D%5B%5D=Served&page=1",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "links": {
        "self": "https://www.servemanager.com/api/jobs/185923"
      },
      "type": "job",
      "id": 185923,
      "servemanager_job_number": "174888",
      "archived_at": null,
      "job_status": "On Hold",
      "service_status": "Served",
      "client_job_number": "ABCD-1234",
      "service_instructions": "Please serve the recipient at the location indicated.\n\nProceeed with caution",
      "due_date": "2015-03-26",
      "rush": true,
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "created_by_id": 1234,
      "recipient": {
        "name": "Bob Jones",
        "description": null,
        "age": null,
        "ethnicity": null,
        "gender": null,
        "weight": null,
        "height1": null,
        "height2": null,
        "hair": null,
        "relationship": null,
        "eyes": null
      },
      "client_company": {
        "links": {
          "self": "https://www.servemanager.com/api/companies/155987"
        },
        "type": "company",
        "name": "Example Law Firm Inc.",
        "collaborating": false,
        "collaboration_account_id": null
      },
      "client_contact": {
        "id": 77777,
        "first_name": "John",
        "last_name": "Doe",
        "title": "Captain",
        "email": "[email protected]",
        "phone": "111-555-8729",
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      },
    "require_server_acceptance": false,
    "server_acceptance_response": null
    "decline_reason": null
    "decline_description": null
    "declined_at": null
      "process_server_company": null,
      "process_server_contact": null,
      "employee_process_server": null,
      "court_case": {
        "links": {
          "self": "https://www.servemanager.com/api/court_cases/111234"
        },
        "type": "court_case",
        "id": 111234,
        "plaintiff": "The Plaintiff",
        "defendant": "The Defendant",
        "filed_date": "2015-03-26",
        "court_date": "2015-05-12",
        "number": "ABC-123",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "court": {
          "links": {
            "self": "https://www.servemanager.com/api/courts/45261"
          },
          "type": "court",
          "id": 45261,
          "branch_name": "Circuit Court",
          "county": "Larimer County",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "created_at": "2015-01-11T06:52:25-05:00",
          "default": false,
          "address": {
            "address1": "555 Example Street",
            "address2": null,
            "city": "Denver",
            "state": "CO",
            "postal_code": "80221"
          }
        }
      },
      "invoice": {
        "type": "invoice",
        "id": 12345,
        "balance_due": "185.0",
        "issued_on": "2015-05-12",
        "total_paid": "0.0",
        "terms": "Thanks for your business. Please pay the \"Balance Due\" within 30 days.",
        "paid_on": null,
        "pdf_download_url": "https://www.servemanager.com/api/v2/invoices/12345/download", // Follow 302 redirects to S3 signed URL
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "line_items": [
          {
            "type": "line_item",
            "id": 123456,
            "name": "3 Attempts",
            "description": "Make up to 3 attempts",
            "unit_cost": "65.0",
            "quantity": "1.0",
            "updated_at": "2015-03-18T10:19:27-04:00",
            "created_at": "2015-01-11T06:52:25-05:00"
          },
          {
            "type": "line_item",
            "id": 123457,
            "name": "Skip Trace",
            "description": "",
            "unit_cost": "25.0",
            "quantity": "1.0",
            "updated_at": "2015-03-18T10:19:27-04:00",
            "created_at": "2015-01-11T06:52:25-05:00"
          }
        ],
        "payments": [
          {
            "type": "payment",
            "id": 222879,
            "amount": "50.0",
            "description": null,
            "applied_on": "2015-05-12",
            "updated_at": "2015-05-12T00:00:00-04:00",
            "created_at": "2015-05-12T00:00:00-04:00"
          }
        ]
      },
      "process_server_invoice": null, // Invoice from the process serving company via collaboration / forwarding, if exists. Same structure as invoice object.
      "addresses_count": 2,
      "addresses": [
        {
          "type": "address",
          "id": 123459,
          "label": "Home",
          "address1": "555 Example Street",
          "address2": null,
          "city": "Denver",
          "state": "CO",
          "postal_code": "80221",
          "county": "Denver County",
          "lat": 55.234,
          "lng": -55.897,
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "primary": true
        },
        {
          "type": "address",
          "id": 123460,
          "label": "Bad Address",
          "address1": "557 Example Street",
          "address2": null,
          "city": "Westminster",
          "state": "CO",
          "postal_code": "80234",
          "county": "Arapahoe County",
          "lat": 99.234,
          "lng": -29.777,
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "primary": false
        }
      ],
      "documents": [
        {
          "type": "document",
          "id": 700,
          "title": "Affidavit of Service",
          "pdf_download_url": "https://www.servemanager.com/api/v2/documents/700/download", // Follow 302 redirects to S3 signed URL
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00"
        }
      ],
      "document_to_be_served_count": 1,
      "document_to_be_served_total_page_count": 5,
      "documents_to_be_served": [
        {
          "type": "document_to_be_served",
          "id": 55588,
          "title": "Summons",
          "received_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "created_at": "2015-01-11T06:52:25-05:00",
          "upload": {
            "file_name": "111-summons.pdf",
            "content_type": "application/pdf",
            "file_size": 324531.0,
            "page_count": 5,
            "links": {
              "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
            }
          }
        }
      ],
      "misc_attachments": [
        {
          "type": "misc_attachment",
          "id": 345956,
          "title": "Photo of Recipient",
          "affidavit": false,
          "affidavit": false,
          "updated_at": "2015-03-18T10:19:27-04:00",
          "created_at": "2015-01-11T06:52:25-05:00",
          "upload": {
            "file_name": "photo-1.jpg",
            "content_type": "image/png",
            "file_size": 225997.0,
            "links": {
              "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
            }
          }
        }
      ],
      "attempts": [
        {
          "type": "attempt",
          "id": 12345,
          "job_id": 9876,
          "description": "Bob Jone answered and accepted the papers.",
          "lat": null,
          "lng": null,
          "serve_type": "Personal/Individual",
          "gps_timestamp": null,
          "device_timestamp": null,
          "gps_accuracy": null,
          "gps_heading": null,
          "gps_speed": null,
          "gps_altitude": null,
          "gps_altitude_accuracy": null,
          "gps_user_agent": null,
          "success": true,
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "attachments": [],
          "servemanager_job_number": 174888,
          "service_status": "Served",
          "server_name": "",
          "served_at": "2015-03-18T10:19:27-04:00",
          "recipient_full_description": "Age: 29; Ethnicity: Caucasian; Gender: Female; Weight: 145; Height: 5'5\"; Hair: Brown; Eyes: Brown; Relationship: Other; Other: Recipient was wearing red overalls and a blue t-shirt",
          "mobile": false,
          "recipient": {
            "name": "Bob Jones",
            "description": "Recipient was wearing red overalls and a blue t-shirt",
            "age": "29",
            "ethnicity": "Caucasian",
            "gender": "Female",
            "weight": "145",
            "height1": "5'",
            "height2": "5\"",
            "hair": "Brown",
            "relationship": "Other",
            "eyes": "Brown"
          },
          "process_server": null,
          "address": {
            "type": "address",
            "id": 123459,
            "label": "Home",
            "address1": "555 Example Street",
            "address2": null,
            "city": "Denver",
            "state": "CO",
            "postal_code": "80221",
            "county": "Denver County",
            "lat": 55.234,
            "lng": -55.897,
            "created_at": "2015-01-11T06:52:25-05:00",
            "updated_at": "2015-03-18T10:19:27-04:00",
            "primary": true
          },
          "visibility": [
              "client"
          ],
          "shared_from": null, // This indicates who shared the attempt. If the current user shared the attempt, the value will be null
          "emailed_to": [
              [
                  "John Doe",
                  "[email protected]"
              ]
          ]
        }
      ],
      "custom": {}
    }
  ]
}

GET /api/jobs/:id

Returns details about a single specific job.

Example Request:

curl https://www.servemanager.com/api/jobs/185923 \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/jobs/185923"
    },
    "type": "job",
    "id": 185923,
    "servemanager_job_number": "174888",
    "archived_at": null,
    "job_status": "On Hold",
    "assigned_by_collaborating_server": false, // Has the assigned collaborating agency assigned the job to a server yet?
    "service_status": "Served",
    "client_job_number": "ABCD-1234",
    "service_instructions": "Please serve the recipient at the location indicated.\n\nProceeed with caution",
    "due_date": "2015-03-26",
    "rush": true,
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "created_by_id": 1234,
    "recipient": {
      "name": "Bob Jones",
      "description": null,
      "age": null,
      "ethnicity": null,
      "gender": null,
      "weight": null,
      "height1": null,
      "height2": null,
      "hair": null,
      "relationship": null,
      "eyes": null
    },
    "duped_from_job_id": 123456, // If applicable, the id of the original job from which this job was duplicated.
    "duped_to_job_id": null, // If applicable, the id of the duplicated job that was created from this original job.
    "job_type_id": null,
    "mailing_date" null,
    "mailed_by_id": null,
    "mailing_location": null,
    "mailing_required": null,
    "instructions_from_client": "The recipient can be located between the hours of 5 PM and 8 PM M-F",
    "client_company": {
      "links": {
        "self": "https://www.servemanager.com/api/companies/155987"
      },
      "type": "company",
      "name": "Example Law Firm Inc.",
      "collaborating": false,
      "collaboration_account_id": null
    },
    "client_contact": {
      "id": 77777,
      "first_name": "John",
      "last_name": "Doe",
      "title": "Captain",
      "email": "[email protected]",
      "phone": "111-555-8729",
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "primary": true
    },
    "require_server_acceptance": true,
    // If applicable, the accept or decline job response of your assigned process server.
    "server_acceptance": {
      "response": "pending", // Either null, "pending", "declined", or "accepted"
      "decline_reason": null,
      "decline_description": null,
      "declined_at": null
    },
    "process_server_company": null,
    "process_server_contact": null,
    "employee_process_server": null,
    "court_case": {
      "links": {
        "self": "https://www.servemanager.com/api/court_cases/111234"
      },
      "type": "court_case",
      "id": 111234,
      "plaintiff": "The Plaintiff",
      "defendant": "The Defendant",
      "filed_date": "2015-03-26",
      "court_date": "2015-05-12",
      "number": "ABC-123",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "court": {
        "links": {
          "self": "https://www.servemanager.com/api/courts/45261"
        },
        "type": "court",
        "id": 45261,
        "branch_name": "Circuit Court",
        "county": "Larimer County",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "default": false,
        "address": {
          "address1": "555 Example Street",
          "address2": null,
          "city": "Denver",
          "state": "CO",
          "postal_code": "80221"
        }
      }
    },
    "invoice": {
      "type": "invoice",
      "id": 12345,
      "balance_due": "185.0",
      "issued_on": "2015-05-12",
      "total_paid": "0.0",
      "terms": "Thanks for your business. Please pay the \"Balance Due\" within 30 days.",
      "paid_on": null,
      "pdf_download_url": "https://www.servemanager.com/api/v2/invoices/12345/download", // Follow 302 redirects to S3 signed URL
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "line_items": [
        {
          "type": "line_item",
          "id": 123456,
          "name": "3
      ",
          "description": "Make up to 3 attempts",
          "unit_cost": "65.0",
          "quantity": "1.0",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "created_at": "2015-01-11T06:52:25-05:00"
        },
        {
          "type": "line_item",
          "id": 123457,
          "name": "Skip Trace",
          "description": "",
          "unit_cost": "25.0",
          "quantity": "1.0",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "created_at": "2015-01-11T06:52:25-05:00"
        }
      ],
      "payments": [
        {
          "type": "payment",
          "id": 222879,
          "amount": "50.0",
          "description": null,
          "applied_on": "2015-05-12",
          "updated_at": "2015-05-12T00:00:00-04:00",
          "created_at": "2015-05-12T00:00:00-04:00"
        }
      ]
    },
    "process_server_invoice": null, // Invoice from the process serving company via collaboration / forwarding, if exists. Same structure as invoice object.
    "addresses_count": 2,
    "addresses": [
      {
        "type": "address",
        "id": 123459,
        "label": "Home",
        "address1": "555 Example Street",
        "address2": null,
        "city": "Denver",
        "state": "CO",
        "postal_code": "80221",
        "county": "Denver County",
        "lat": 55.234,
        "lng": -55.897,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      },
      {
        "type": "address",
        "id": 123460,
        "label": "Bad Address",
        "address1": "557 Example Street",
        "address2": null,
        "city": "Westminster",
        "state": "CO",
        "postal_code": "80234",
        "county": "Arapahoe County",
        "lat": 99.234,
        "lng": -29.777,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": false
      }
    ],
    "documents": [
      {
        "type": "document",
        "id": 1594424,
        "title": "Nationwide Affidavit",
        "pdf_download_url": "https://www.servemanager.com/api/v2/documents/1594424/download",
        "signed": true,
        "created_at": "2023-08-17T00:22:51-06:00",
        "updated_at": "2023-08-17T00:22:51-06:00"
      }
    ],
    "document_to_be_served_count": 1,
    "document_to_be_served_total_page_count": 5,
    "documents_to_be_served": [
      {
        "type": "document_to_be_served",
        "id": 55588,
        "title": "Summons",
        "affidavit": false",
        "signed": false",
        "received_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "upload": {
          "id": 245296",
          "file_name": "111-summons.pdf",
          "content_type": "application/pdf",
          "file_size": 324531.0,
          "page_count": 5,
          "record_type": "job",
          "record_id": 185923,
          "links": {
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
          }
        }
      }
    ],
    "misc_attachments_count": 1,
    "misc_attachments": [
      {
        "type": "misc_attachment",
        "id": 345956,
        "title": "Photo of Recipient",
        "affidavit": false,
        "signed": false,
        "received_at": null,
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "upload": {
          "id": 245296",
          "file_name": "photo-1.jpg",
          "content_type": "image/png",
          "file_size": 225997.0,
          "page_count": 0,
          "record_type": "job",
          "record_id": 185923,
          "links": {
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
          }
        }
      }
    ],
    "attempt_count": 1,
    "last_attempt_served_at": "2015-03-18T10:19:27-04:00",
    "last_attempt_served_at_timezone": "America/Chicago",
    "attempts": [
      {
        "type": "attempt",
        "id": 12345,
        "job_id": 9876,
        "description": "Bob Jone answered and accepted the papers.",
        "lat": null,
        "lng": null,
        "serve_type": "Personal/Individual",
        "gps_timestamp": null,
        "device_timestamp": null,
        "gps_accuracy": null,
        "gps_heading": null,
        "gps_speed": null,
        "gps_altitude": null,
        "gps_altitude_accuracy": null,
        "gps_user_agent": null,
        "success": true,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "attachments": [],
        "servemanager_job_number": 174888,
        "service_status": "Served",
        "server_name": "",
        "served_at": "2015-03-18T10:19:27-04:00",
        "recipient_full_description": "Age: 29; Ethnicity: Caucasian; Gender: Female; Weight: 145; Height: 5'5\"; Hair: Brown; Eyes: Brown; Relationship: Other; Other: Recipient was wearing red overalls and a blue t-shirt",
        "mobile": false,
        "recipient": {
          "name": "Bob Jones",
          "description": "Recipient was wearing red overalls and a blue t-shirt",
          "age": "29",
          "ethnicity": "Caucasian",
          "gender": "Female",
          "weight": "145",
          "height1": "5'",
          "height2": "5\"",
          "hair": "Brown",
          "relationship": "Other",
          "eyes": "Brown"
        },
        "process_server": null,
        "address": {
          "type": "address",
          "id": 123459,
          "label": "Home",
          "address1": "555 Example Street",
          "address2": null,
          "city": "Denver",
          "state": "CO",
          "postal_code": "80221",
          "county": "Denver County",
          "lat": 55.234,
          "lng": -55.897,
          "created_at": "2015-01-11T06:52:25-05:00",
          "updated_at": "2015-03-18T10:19:27-04:00",
          "primary": true
        },
        "visibility": [
            "client"
        ],
        "shared_from": null, // This indicates who shared the attempt. If the current user shared the attempt, the value will be null
        "emailed_to": [
            [
                "John Doe",
                "[email protected]"
            ]
        ]
      }
    ],
    "custom": {}
  }
}

POST /api/jobs

Creates a new job with the specified attributes. Only type is required

Attribute Description
type * MUST be equal to "job". Any other value causes a 409 CONFLICT error.
client_company_id Id of the client company for the job. See the companies API to get company ids.
client_contact_id Id of the client company's contact for the job. See the companies API to get contact ids.
process_server_company_id Id of the process server company for the job. See the companies API to get company ids. If this is present, employee_process_server_id CANNOT be present.
process_server_contact_id Id of the server company's contact for the job. See the companies API to get contact ids.
employee_process_server_id Id for an employee assigned to the job. See the employees API to get employee ids.
require_server_acceptance A true or false value to indicate whether or not the job should require the Process Server to accept or decline the job. Defaults to false.
notify_server A true or false value to indicate whether an email is sent to the server notifying them of the new job. Defaults to false.
court_case_id Id for the job's court case. Use the court cases API to get court case ids or create new court cases for the job
due_date A date that should match the formatting specified by the Date Formatting section
service_instructions
client_job_number The client reference number for the job
rush A true or false value to indicate whether or not the job is a rush job or not. Defaults to false.
job_status The user-customizable job status on the job. See the possible values section for more information.
recipient_attributes A JSON object of the recipient for the job. Example:
{
  "recipient_attributes":{
    "name":"John Doe",
    "description":"Has a tattoo of an eagle on his left arm",
    "age":"28",
    "ethnicity":"Caucasian",
    "gender":"Male",
    "weight":"155",
    "height1":"5'",
    "height2":"11\"",
    "hair":"Brown",
    "eyes":"Hazel"
  }
}
recipient_attributes['name'] The recipient's name
recipient_attributes['description'] Custom description for the recipient
recipient_attributes['age'] Recipient's age. See possible values for details.
recipient_attributes['ethnicity'] Recipient's ethnicity. See possible values for details.
recipient_attributes['gender'] Recipient's gender. See possible values for details.
recipient_attributes['weight'] Recipient's weight (any value allowed)
recipient_attributes['height1'] Recipient's feet height. See possible values for details.
recipient_attributes['height2'] Recipient's inches height. See possible values for details.
recipient_attributes['hair'] Recipient's hair color. See possible values for details.
recipient_attributes['eyes'] Recipient's eye color. See possible values for details.
addresses_attributes

Must be an array of JSON address objects to be created. Example:

{
  "addresses_attributes": [
    {
      "label":"Branch",
      "address1":"555 Example Street",
      "city":"Denver",
      "state":"CO",
      "postal_code":"80221",
      "county":"Denver County",
      "primary":true
    }
  ]
}
addresses_attributes['label'] Label of the address. See possible values above.
addresses_attributes['address1'] Address line 1
addresses_attributes['address2'] Address line 2
addresses_attributes['city']
addresses_attributes['state']
addresses_attributes['postal_code'] Zip code for address
addresses_attributes['county'] County for the address
addresses_attributes['primary'] true or false - primary address for the company
documents_to_be_served_attributes

Must be an array of JSON document objects to be created. Example:

{
  "documents_to_be_served_attributes": [
    {
      "title":"Subpoena",
      "received_at":"2015-02-13T15:49:00.000-06:00",
      "external_url":"http://www.example.com/subpoena_file.pdf",
      "file_name":"subpoena_file.pdf",
      "reference_number":"94HY39F"
    }
  ]
}
documents_to_be_served_attributes['title'] The title of the document. Defaults to the file_name if left blank.
documents_to_be_served_attributes['received_at'] The date and time that the document was received. Should match the datetime format specified in the Date Formatting section.
documents_to_be_served_attributes['external_url'] If you provide this field, the file accessible at external_url will be downloaded and automatically attached to the job as if you had uploaded the file yourself. This is the simplest method to attach files to jobs, but you need to ensure the file is accessible at the provided URL.
documents_to_be_served_attributes['file_name']

The name of a file that is attached to the job. Note that if you want multiple electronic files attached, you MUST send multiple documents_to_be_served or misc_attachments nodes with one file_name each.

If you provided an external_url, no further action needs to be taken, and no put_url will exist in the response payload.

If you do NOT provide an external_url, the response will then include a put_url for each document_to_be_served that was created, which you should use to individually PUT files so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. See the document upload example.

documents_to_be_served_attributes['reference_number']

Optional field to specify the a reference number for the document. This is used to match the document to the API reference number in the system.

misc_attachments_attributes

Must be an array of JSON misc_attachment objects to be created. Example:

{
  "misc_attachments_attributes": [
    {
      "title":"Photo of Recipient",
      "file_name":"photo.png",
      "reference_number":"94HY39F"
    }
  ]
}
misc_attachments_attributes['title'] The title of the attachment
misc_attachments_attributes['file_name'] The filename of the misc attachment. Note that if you want multiple electronic files attached, you MUST send multiple documents_to_be_served or misc_attachments nodes with one file_name each. The response will then include a put_url for each file that was created, which you should use to individually PUT files to so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. (See 'Document Upload' examples below)
misc_attachments_attributes['reference_number']

Optional field to specify the a reference number for the document. This is used to match the document to the API reference number in the system.

Example Request (With Document):

curl https://www.servemanager.com/api/jobs \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"job","job_status":"On Hold","documents_to_be_served_attributes":[{"file_name":"the_subpoena.pdf","title":"Subpoena","received_at":"2015-01-11T06:52:25-05:00"}]}}'

Example Response:

{
  "data": {
    "links": {
      "self": "https://www.servemanager.com/api/jobs/593421"
    },
    "type": "job",
    "id": 593421,
    "servemanager_job_number": "517063",
    "archived_at": null,
    "job_status": "On Hold",
    "service_status": null,
    "client_job_number": null,
    "service_instructions": null,
    "due_date": null,
    "rush": false,
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "created_by_id": null,
    "recipient": null,
    "client_company": null,
    "client_contact": null,
    "require_server_acceptance": false,
    "server_acceptance_response": null
    "decline_reason": null
    "decline_description": null
    "declined_at": null
    "process_server_company": null,
    "process_server_contact": null,
    "employee_process_server": null,
    "court_case": null,
    "invoice": {
      "type": "invoice",
      "id": 445758,
      "balance_due": "0.0",
      "issued_on": null,
      "total_paid": "0.0",
      "terms": "Thanks for your business. Please pay the \"Balance Due\" within 30 days.",
      "paid_on": null,
      "updated_at": "2015-01-11T06:52:25-05:00",
      "created_at": "2015-03-18T10:19:27-04:00",
      "line_items": [

      ],
      "payments": [

      ]
    },
    "process_server_invoice": null,
    "addresses_count": 2,
    "addresses": [
      {
        "type": "address",
        "id": 570947,
        "label": "Home",
        "address1": "315 Parkview Drive",
        "address2": "Lot 61",
        "city": "Bowling Green",
        "state": "OH",
        "postal_code": "43402",
        "county": null,
        "lat": 41.3895123,
        "lng": -83.6473438,
        "created_at": "2015-03-13T07:51:05-04:00",
        "updated_at": "2015-03-13T07:51:05-04:00",
        "primary": true
      },
      {
        "type": "address",
        "id": 570948,
        "label": "Mother's Home",
        "address1": "1432 Devonshire Street",
        "address2": "",
        "city": "Bowlng Green",
        "state": "OH",
        "postal_code": "43402",
        "county": null,
        "lat": 41.378376,
        "lng": -83.679293,
        "created_at": "2015-03-13T07:53:18-04:00",
        "updated_at": "2015-03-13T07:53:18-04:00",
        "primary": false
      }
    ],
    "documents": [

    ],
    "document_to_be_served_count": 1,
    "document_to_be_served_total_page_count": null,
    "documents_to_be_served": [
      {
        "type": "document_to_be_served",
        "id": 214199,
        "reference_number": "94HY39F",
        "title": "Subpoena",
        "received_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-01-11T06:52:25-05:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "upload": {
          "file_name": "the_subpoena.pdf",
          "content_type": null,
          "file_size": null,
          "page_count": null,
          "links": {
            "put_url": "https://PUT_URL_FROM_JOB_CREATE_RESPONSE",
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
          }
        }
      }
    ],
    "misc_attachments": [

    ],
    "attempts": [

    ],
    "custom": {}
  }
}

Example Document Upload Request

curl -X PUT \
  "https://PUT_URL_FROM_JOB_CREATE_RESPONSE" \
  --upload-file ~/Documents/Files/the_subpoena.pdf

PUT /api/jobs/:id

Updates an existing job

Attributes allowed here are identical to those found in the jobs create endpoint. All attributes are optional, and any included attributes will update the existing data on the job with the following exceptions:

Attribute Description
addresses_attributes Accepts the same format as the create endpoint, however any addresses included here will be added to the job. Existing addresses on the job will remain unchanged, and the API does not currently provide a way to remove addresses from a job.
documents_to_be_served_attributes Like addresses, documents_to_be_served will be appended to the job. No documents will be edited or removed via this endpoint.
misc_attachments_attributes No misc_attachments will be edited or removed. Any attributes included here will be added to the existing job.

Example Request:

curl https://www.servemanager.com/api/jobs/1234 -X PUT \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"job","client_job_number":"ABC-1234","addresses_attributes":[{"address1":"555 Yorkshire Ave","city":"Westminster","state":"CO"}]}}'

Uploads

POST /api/jobs/:id/uploads

Creates attachments for a job. This is used to upload files to a job that was created without files. The response will include a put_url for each file that was created, which you should use to individually PUT files to so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created.

Attribute Description
type * MUST be equal to "misc_attachment" or "document_to_be_served" or "attachment". Any other value causes a 409 CONFLICT error. If you use "attachment" you are expected to send individual `upload_type` fields for each upload.
visibility

Must be an array of visibility parameters. Accepted values are
"client" and/or "server". If no visibility parameter is sent, it will default to account visibility settings. If an empty array is sent, it will override account visibility settings and not make the document visible to client or server.
Example:

{
  "visibility": ["client", "server"]
}
email_to

Must be an array containing "client" and/or "server". This paramater can also include a name and email values within each individual array.
Example:

{
  "email_to": ["client", ["John Doe", "[email protected]"]]
}
message This will be the message that is sent with an email when email_to param is included. This is optional.
attachments_attributes Must be an array of JSON misc_attachment objects to be created. Example:
{
  attachments_attributes: [
    {
      title: "Subpoena",
      file_name: "the_subpoena.pdf",
      affidavit: true,
      signed: false,
      upload_type: "document_to_be_served"
    }
  ]
}
attachments_attributes['upload_type']

This field is required if you are using the "attachment" type. It should be equal to "document_to_be_served" or "misc_attachment", any other value will default to "misc_attachment".

attachments_attributes['title'] The title of the document. Defaults to the file_name if not provided.
attachments_attributes['file_name']

If you provided an external_url, no further action needs to be taken, and no put_url will exist in the response payload.

If you do NOT provide an external_url, the response will then include a put_url for the document_to_be_served or misc_attachment that was created, which you should use to individually PUT files so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. See the document upload example.

attachments_attributes['external_url'] If you provide this field, the file accessible at external_url will be downloaded and automatically attached to the job as if you had uploaded the file yourself. This is the simplest method to attach files to jobs, but you need to ensure the file is accessible at the provided URL.
attachments_attributes['reference_number']

Optional field to specify the a reference number for the document. This is used to match the document to the API reference number in the system.

attachments_attributes['received_at'] The date and time that the document was received. Should match the datetime format specified in the Date Formatting section.
attachments_attributes['affidavit'] This will be either true or false. If true, the document will be treated as an affidavit. If false, the document will be treated as a regular document.
attachments_attributes['signed'] This will be either true or false. This is in addition to affidavit to mark when the affidavit is signed. If true, the document will be treated as signed. If false, the document will be treated as unsigned.

Example Request:

curl https://www.servemanager.com/api/jobs/185923 \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"misc_attachment", "visibility":["client","server"], "email_to":["client",["John Doe", "[email protected]"]]", "message":"Please review the documents attached.", attachments_attributes":[{"title":"Subpoena","file_name":"the_subpoena.pdf","affidavit":true,"signed":false}]}}'

Example Response:

{
  "data": [
    {
      "type": "misc_attachment",
      "id": 593421,
      "title": "Subpoena",
      "reference_number": "34FHY5",
      "affidavit": true,
      "signed": false,
      "received_at": null,
      "updated_at": "2015-03-18T10:19:27-04:00",
      "created_at": "2015-01-11T06:52:25-05:00",
      "upload": {
        "id": 214199,
        "file_name": "the_subpoena.pdf",
        "content_type": null,
        "file_size": 0,
        "page_count": 0,
        "record_type": "job",
        "record_id": "185923",
        "links": {
          "put_url": "https://PUT_URL_FROM_JOB_CREATE_RESPONSE",
          "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
        }
      },
      "visibility": [
        "client",
        "server"
      ],
      "shared_from": null,
      "emailed_to": [
        [
            "Lionel Stanton",
            "[email protected]"
        ],
        [
          "John Doe",
          "[email protected]"
        ]
      ],
      "message": "Please review the documents attached."
    }
  ]
}

Notes

POST /api/jobs/:job_id/notes

Creates a new job note with the specified attributes. Only type and body are required

Attribute Description
type * MUST be equal to "note". Any other values causes a 409 CONFLICT error.
label
body *
category_id
visibility

Must be an array of visibility parameters. Accepted values are
"client" and/or "server"
Example:

{
  "visibility": ["client"]
}
email_to

Must be an array of arrays containing name and email values within each individual array. Also allowed are special keywords "client" , or "server" which will send email notifications to the job's client company contact, and the job's process server contact, respectively.
Example:

{
  "email_to": [["John Doe", "[email protected]"], ["Jane Doe", "[email protected]], "server"]
}

Example Request:

curl https://www.servemanager.com/api/jobs/123/notes \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"note","label":"My Note","body":"Read this note", "visibility": ["client"], "category_id": 1, "email_to": [["John Doe", "[email protected]"], "server"]}'

Example Response:

{
  "data": {
    "links": {
    },
    "type": "note",
    "id": 4567,
    "label": "My Note",
    "body": "Read this note",
    "job_id": 123,
    "updated_at": "2015-03-18T10:19:27-04:00",
    "created_at": "2015-01-11T06:52:25-05:00",
    "created_by": "Jane Doe",
    "category_id": 1,
    "visibility": [
        "client"
    ],
    "shared_from": null,
    "emailed_to": [
        [
            "John Doe",
            "[email protected]"
        ],
        [
            "Jane Doe",
            "[email protected]"
        ]
    ]
  }
}

GET /api/jobs/:job_id/notes

Returns an array of notes within a job

Pagination may be utilized here. Please see the Pagination section for more details.

Example Request:

curl https://www.servemanager.com/api/jobs/123/notes \
  -u ${API_KEY}: \

GET /api/notes

Returns an array of all notes within an account

Pagination may be utilized here. Please see the Pagination section for more details.

Example Request:

curl https://www.servemanager.com/api/notes \
  -u ${API_KEY}: \

Example Response:

{
  "links": {
      "self": "https://www.servemanager.com/api/notes?page=1",
      "first": "https://www.servemanager.com/api/notes?page=1",
      "last": "https://www.servemanager.com/api/notes?page=1",
      "prev": null,
      "next": "https://www.servemanager.com/api/notes?page=1"
  },
  "data": [
    {
      "links": {},
      "type": "note",
      "id": 1533161,
      "label": "Notice",
      "body": "New address on file",
      "job_id": 552112,
      "updated_at": "2021-05-13T13:34:12-06:00",
      "created_at": "2021-05-13T13:34:12-06:00",
      "created_by": "Jane Doe",
      "visibility": [],
      "shared_from": null,
      "emailed_to": []
    },
    {
      "links": {},
      "type": "note",
      "id": 1533160,
      "label": "Called",
      "body": "Called Bill about payment",
      "job_id": 552112,
      "updated_at": "2021-05-13T13:34:11-06:00",
      "created_at": "2021-05-13T13:34:11-06:00",
      "created_by": "Jane Doe",
      "visibility": [
        "client"
      ],
      "shared_from": null,
      "emailed_to": [
          [
              "John Doe",
              "[email protected]"
          ]
      ]
    }
  ]
}

Attempts

Enumerated Attempt Attributes:

Attribute name Default values Supports custom value?
data['serve_type']
  • Successful Values: "Authorized", "Business", "Corporation", "Government Agency", "Mail", "Personal/Individual", "Posted", "Registered Agent", "Secretary of State", "Substitute Service - Abode", "Substitute Service - Business", "Substitute Service - Personal"
  • Unsuccessful Values: "Bad Address", "Non-Service", "Unsuccessful Attempt"
No
data['recipient']['ethnicity'] "", "African American", "Asian American", "Caucasian", "Hispanic", "Latino", "Middle Eastern", "Native American", "Native Hawaiian", "Other" No
data['recipient']['gender'] "", "Male", "Female", "Other" No
data['recipient']['height1'] "", "3'", "4'", "5'", "6'", "7'", "8'", "9'" No
data['recipient']['height2'] '', '1"','2"','3"','4"','5"','6"','7"','8"','9"','10"','11"','12"' No
data['recipient']['hair'] "", "Bald", "Black", "Blond", "Brown", "Gray", "Red", "White", "Other" No
data['recipient']['eyes'] "", "Amber", "Black", "Blue", "Brown", "Gray", "Green", "Hazel", "Other" No
data['recipient']['relationship'] "", "Aunt", "Boyfriend", "Brother", "Cousin", "Daughter", "Father", "Girlfriend", "Grandfather", "Grandmother", "Husband", "Mother", "Partner", "Nephew", "Niece", "Sister", "Son", "Uncle", "Wife", "Other" Yes
data['address']['label'] "", "Company", "Corporate", "Branch", "Home" Yes

GET /api/attempts

Returns an array of attempts and details about them.

Pagination may be utilized here. Please see the Pagination section for more details.

Example Request:

curl https://www.servemanager.com/api/attempts
  -u ${API_KEY}:

Example Response:

{
  "links": {
    "self": "https://www.servemanager.com/api/attempts?page=1",
    "first": "https://www.servemanager.com/api/attempts?page=1",
    "last": "https://www.servemanager.com/api/attempts?page=1",
    "prev": null,
    "next": null
  },
  "data": [
    {
      "type": "attempt",
      "id": 12345,
      "job_id": 9876,
      "description": "Bob Jone answered and accepted the papers.",
      "lat": null,
      "lng": null,
      "serve_type": "Personal/Individual",
      "gps_timestamp": null,
      "device_timestamp": null,
      "gps_accuracy": null,
      "gps_heading": null,
      "gps_speed": null,
      "gps_altitude": null,
      "gps_altitude_accuracy": null,
      "gps_user_agent": null,
      "success": true,
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "attachments": [],
      "servemanager_job_number": 1234,
      "service_status": "Served",
      "server_name": "",
      "served_at": "2015-03-18T10:19:27-04:00",
      "recipient_full_description": "Age: 29; Ethnicity: Caucasian; Gender: Female; Weight: 145; Height: 5'5\"; Hair: Brown; Eyes: Brown; Relationship: Other; Other: Recipient was wearing red overalls and a blue t-shirt",
      "mobile": false,
      "recipient": {
        "name": "Bob Jones",
        "description": "Recipient was wearing red overalls and a blue t-shirt",
        "age": "29",
        "ethnicity": "Caucasian",
        "gender": "Female",
        "weight": "145",
        "height1": "5'",
        "height2": "5\"",
        "hair": "Brown",
        "relationship": "Other",
        "eyes": "Brown"
      },
      "process_server": null,
      "address": {
        "type": "address",
        "id": 123459,
        "label": "Home",
        "address1": "555 Example Street",
        "address2": null,
        "city": "Denver",
        "state": "CO",
        "postal_code": "80221",
        "county": "Denver County",
        "lat": 55.234,
        "lng": -55.897,
        "created_at": "2015-01-11T06:52:25-05:00",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "primary": true
      },
      "visibility": [],
      "shared_from": null, // This indicates who shared the attempt. If the current user shared the attempt, the value will be null
      "emailed_to": [
          [
              "John Doe",
              "[email protected]"
          ]
      ]
    }
  ]
}

GET /api/attempts/:id

Returns details about a single specific attempt.

Example Request:

curl https://www.servemanager.com/api/attempts/12345 \
  -u ${API_KEY}:

Example Response:

{
  "data": {
    "type": "attempt",
    "id": 12345,
    "job_id": 9876,
    "description": "Bob Jone answered and accepted the papers.",
    "lat": null,
    "lng": null,
    "serve_type": "Personal/Individual",
    "gps_timestamp": null,
    "device_timestamp": null,
    "gps_accuracy": null,
    "gps_heading": null,
    "gps_speed": null,
    "gps_altitude": null,
    "gps_altitude_accuracy": null,
    "gps_user_agent": null,
    "success": true,
    "created_at": "2015-01-11T06:52:25-05:00",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "attachments": [],
    "servemanager_job_number": 1234,
    "service_status": "Served",
    "server_name": "",
    "served_at": "2015-03-18T10:19:27-04:00",
    "recipient_full_description": "Age: 29; Ethnicity: Caucasian; Gender: Female; Weight: 145; Height: 5'5\"; Hair: Brown; Eyes: Brown; Relationship: Other; Other: Recipient was wearing red overalls and a blue t-shirt",
    "mobile": false,
    "recipient": {
      "name": "Bob Jones",
      "description": "Recipient was wearing red overalls and a blue t-shirt",
      "age": "29",
      "ethnicity": "Caucasian",
      "gender": "Female",
      "weight": "145",
      "height1": "5'",
      "height2": "5\"",
      "hair": "Brown",
      "relationship": "Other",
      "eyes": "Brown"
    },
    "process_server": null,
    "address": {
      "type": "address",
      "id": 123459,
      "label": "Home",
      "address1": "555 Example Street",
      "address2": null,
      "city": "Denver",
      "state": "CO",
      "postal_code": "80221",
      "county": "Denver County",
      "lat": 55.234,
      "lng": -55.897,
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "primary": true
    },
    "visibility": [],
    "shared_from": null, // This indicates who shared the attempt. If the current user shared the attempt, the value will be null
    "emailed_to": [
        [
            "John Doe",
            "[email protected]"
        ]
    ]
  }
}

POST /api/jobs/:job_id/attempts

Creates a new attempt with the specified attributes for an EXISTING job. serve_type , served_at , address (data), recipient_name (if successful) and type are required

Attribute Description
type * MUST be equal to "attempt". Any other value causes a 409 CONFLICT error.
serve_type * The attempt's type. See for the valid types.
served_at * A date that should match the formatting specified by the Date Formatting section
process_server_id Id of the process server employee for the attempt. If this is present, server_name CANNOT be present.
server_name Name of the server for the attempt. If this is present, process_server_id CANNOT be present.
description
recipient_name * The recipient's name
recipient_description Custom description for the recipient
recipient_age Recipient's age. See possible values for details.
recipient_ethnicity Recipient's ethnicity. See possible values for details.
recipient_gender Recipient's gender. See possible values for details.
recipient_weight Recipient's weight (any value allowed)
recipient_height1 Recipient's feet height. See possible values for details.
recipient_height2 Recipient's inches height. See possible values for details.
recipient_hair Recipient's hair color. See possible values for details.
recipient_eyes Recipient's eye color. See possible values for details.
address_id * The id of an existing address you own. If this is present, address_attributes CANNOT be present, if not, you should send address_attributes as new address.
address_attributes *

Must be a hash of JSON address to be created. Example:

{
  "addresses_attributes":
    {
      "label":"Branch",
      "address1":"555 Example Street",
      "address2":"Suite #1",
      "city":"Denver",
      "state":"CO",
      "postal_code":"80221",
      "county":"Denver County",
    }
}

If this is present, address_id CANNOT be present.

lat Geocode lat value
lng Geocode lng value
gps_timestamp
device_timestamp
gps_accuracy
gps_heading
gps_speed
gps_altitude
gps_altitude_accuracy
gps_user_agent
attachments_attributes

Must be an array of JSON attachment objects to be created. Example:

{
  "attachments_attributes": [
    {
      "title":"Photo of Home",
      "external_url":"http://www.example.com/house.jpg"
      "file_name":"photo_of_home1.jpg"
    }
  ]
}
attachments_attributes['title'] The title of the attachment
attachments_attributes['external_url'] If you provide this field, the file accessible at external_url will be downloaded and automatically attached to the attempt as if you had uploaded the file yourself. This is the simplest method to attach files to attempts, but you need to ensure the file is accessible at the provided URL.
attachments_attributes['file_name']

The name of the attachment. Note that if you want multiple electronic files attached, you MUST send multiple attachment nodes with one file_name each.

If you provided an external_url, no further action needs to be taken, and no put_url will exist in the response payload.

If you do NOT provide an external_url, the response will then include a put_url for each document_to_be_served that was created, which you should use to individually PUT files to so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. See the document upload example.

attachment['reference_number']

Optional field to specify the a reference number for the document. This is used to match the document to the API reference number in the system.

visibility

Must be an array of visibility parameters. Accepted values are
"client" and/or "server"
Example:

{
  "visibility": ["client"]
}
email_to

Must be an array of arrays containing name and email values within each individual array.
Example:

{
  "email_to": [["John Doe", "[email protected]"], ["Jane Doe", "[email protected]]]
}

Example Request:

curl https://www.servemanager.com/api/jobs/1/attempts \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"attempt", "serve_type":"Personal/Individual", "description": "Served", "server_name":"Pepe", "recipient_name": "Bob Jones", "served_at":"2017-01-11T06:52:25-05:00", "address_attributes": {"city":"Denver"}, "attachments_attributes":[{"file_name":"attachment_file.pdf","title":"Attachment"}], "visibility": ["client"], "email_to": [["John Doe", "[email protected]"], ["Jane Doe", "[email protected]"]]}}'

Example Response:

{
  "data": {
    "type": "attempt",
    "id": 12345,
    "job_id": 9876,
    "description": "Bob Jone answered and accepted the papers.",
    "lat": null,
    "lng": null,
    "serve_type": "Personal/Individual",
    "gps_timestamp": null,
    "device_timestamp": null,
    "gps_accuracy": null,
    "gps_heading": null,
    "gps_speed": null,
    "gps_altitude": null,
    "gps_altitude_accuracy": null,
    "gps_user_agent": null,
    "success": true,
    "created_at": "2015-01-11T06:52:25-05:00",
    "updated_at": "2015-03-18T10:19:27-04:00",
    "attachments": [
      {
        "type": "attachment",
        "reference_number": "94HY39F",
        "id": 551916,
        "title": "Photo of Home",
        "updated_at": "2015-03-18T10:19:27-04:00",
        "created_at": "2015-01-11T06:52:25-05:00",
        "upload": {
          "file_name": "photo_of_home1.jpg",
          "content_type": "image/jpg",
          "file_size": 31415.9,
          "links": {
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON",
            "put_url": "https://PUT_URL_FROM_ATTEMPT_CREATE_RESPONSE"
          }
        }
      }
    ],
    "servemanager_job_number": 1234,
    "service_status": "Served",
    "server_name": "",
    "served_at": "2015-03-18T10:19:27-04:00",
    "recipient_full_description": "Age: 29; Ethnicity: Caucasian; Gender: Female; Weight: 145; Height: 5'5\"; Hair: Brown; Eyes: Brown; Relationship: Other; Other: Recipient was wearing red overalls and a blue t-shirt",
    "mobile": false,
    "recipient": {
      "name": "Bob Jones",
      "description": "Recipient was wearing red overalls and a blue t-shirt",
      "age": "29",
      "ethnicity": "Caucasian",
      "gender": "Female",
      "weight": "145",
      "height1": "5'",
      "height2": "5\"",
      "hair": "Brown",
      "relationship": "Other",
      "eyes": "Brown"
    },
    "process_server": null,
    "address": {
      "type": "address",
      "id": 123459,
      "label": "Home",
      "address1": "555 Example Street",
      "address2": null,
      "city": "Denver",
      "state": "CO",
      "postal_code": "80221",
      "county": "Denver County",
      "lat": 55.234,
      "lng": -55.897,
      "created_at": "2015-01-11T06:52:25-05:00",
      "updated_at": "2015-03-18T10:19:27-04:00",
      "primary": true
    },
    "visibility": [
      "client"
    ],
    "shared_from": null, // This indicates who shared the attempt. If the current user shared the attempt, the value will be null
    "emailed_to": [
        [
            "John Doe",
            "[email protected]"
        ],
        [
            "Jane Doe",
            "[email protected]"
        ]
    ]
  }
}

PUT /api/attempts/:id

Updates an existing attempt with the specified attributes.

Attributes allowed here are identical to those found in the Attempts#Create endpoint. All attributes are optional and any included attributes will update the existing data on the attempt with the following exceptions:

Attribute Description
attachments_attributes Accepts the same format as the create endpoint, however any attachments included here will be added to the attempt. Existing attachments on the attempt will remain unchanged.
lat GPS attributes cannot be updated from an existing attempt.
lng
gps_timestamp
device_timestamp
gps_accuracy
gps_heading
gps_speed
gps_altitude
gps_altitude_accuracy
gps_user_agent

Example Request:

curl https://www.servemanager.com/api/attempts/:id - X PUT\
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"attempt", "service_type_id":294835, "recipient_name": "Bob Jones", "served_at":"2017-01-11T06:52:25-05:00", "address_attributes": {"city":"Denver"}, "attachments_attributes":[{"file_name":"attachment_file.pdf","title":"Attachment"}], "visibility": ["client"], "email_to": [["John Doe", "[email protected]"], ["Jane Doe", "[email protected]"]]}}'

DELETE /api/attempts/:id

Deletes an existing attempt.

Example Request:

curl https://www.servemanager.com/api/attempts/:id - X DELETE \
  -u ${API_KEY}: \
  -H "Content-Type: application/json"

Invoices

POST /api/jobs/:id/invoices

Creates an invoice for a specific job with the specified attributes.

Attribute Description
type *

MUST be equal to "invoice". Any other value causes a 409 CONFLICT error.

issued_on

The date the invoice was issued in ISO 8601 format.
Example:

{
  "issued_on": "2024-05-13"
}
terms

The terms of the invoice.

line_items_attributes

Must be an array of JSON objects representing the line items.
Example:

{
  "line_items_attributes": [
    {
      "name": "Rush Service",
      "description": "Fee for rush service.",
      "unit_cost": 80,
      "quantity": 1
    }
  ]
}
line_items_attributes['name']

The name of the line item or service provided.

line_items_attributes['description']

Additional description for the line item.

line_items_attributes['unit_cost']

Must be an integer representing the cost per unit.

line_items_attributes['tax_rate']

When enabled, a percentage value can be applied to the specified line item. tax_rate: 3.45 would be a 3.45% tax rate.

line_items_attributes['quantity']

The quantity of the line item. This value is multiplied by the unit cost to determine the total cost.

Example Request:

curl https://www.servemanager.com/api/jobs/185923 \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"invoice", "terms":"Please pay the invoice within 14 days of receipt", "issued_on": "2024-05-13", "line_items_attributes":[{"name": "Service Fee", description: "Local non-rush service fee", "unit_cost": 75, "tax_rate": 5, "quantity": 1}]}}'

Example Response:

{
  "data": {
    "type": "invoice",
    "id": 2698492,
    "balance_due": "105.0",
    "locked": false,
    "issued_on": null,
    "total_paid": "0.0",
    "total": "105.0",
    "terms": "Please pay the invoice within 14 days of receipt",
    "paid_on": null,
    "job_id": 185923,
    "token": null,
    "taxes_enabled": false,
    "last_issued_at": null,
    "updated_at": "2024-05-13T10:07:21-06:00",
    "created_at": "2024-05-13T10:07:21-06:00",
    "client_id": null,
    "servemanager_job_number": 4354213,
    "pdf_download_url": "http://servemanager.com/api/v2/invoices/2698492/download",
    "line_items": [
      {
        "type": "line_item",
        "id": 3005323,
        "name": "Service Fee",
        "description": "Local non-rush service fee",
        "unit_cost": "75.0",
        "quantity": "1.0",
        "tax_rate": "5.0",
        "tax_amount": "3.75",
        "subtotal": "75.0",
        "total": "78.75",
        "updated_at": "2024-05-13T10:07:21-06:00",
        "created_at": "2024-05-13T10:07:21-06:00"
      }
    ],
    "payments": []
  }
}

PUT /api/invoices/:id

Updates an existing invoice. All attributes are optional except for type , which is required. The included attributes will update the existing data on the invoice. Line items can be updated or destroyed with id using the following structure:

Attribute Description
line_items_attributes To update or destroy an existing line_item, an "id" must be provided. To destroy a line item, set the "_destroy" attribute to true.
Example:
{
  "line_items_attributes": [
    {
      "id": 294852,
      "_destroy": true
    }
  ]
}

Example Request:

curl https://www.servemanager.com/api/jobs/185923 \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"invoice", "line_items_attributes":[{"id": 482954, "name": "Standard Service Fee", description: "Local non-rush service fee", "unit_cost": 75, "quantity": 1}, {"name": "Multiple Attempt Fee", description: "Additional fee for several attempts", "unit_cost": 10, "quantity": 1}]}}'

Example Response:

{
  "data": {
    "type": "invoice",
    "id": 2698492,
    "balance_due": "85.0",
    "locked": false,
    "issued_on": null,
    "total_paid": "0.0",
    "total": "85.0",
    "terms": "Please pay the invoice within 14 days of receipt",
    "paid_on": null,
    "job_id": 185923,
    "token": null,
    "taxes_enabled": false,
    "last_issued_at": null,
    "updated_at": "2024-05-13T10:07:21-06:00",
    "created_at": "2024-05-13T10:07:21-06:00",
    "client_id": null,
    "servemanager_job_number": 4354213,
    "pdf_download_url": "http://servemanager.com/api/v2/invoices/2698492/download",
    "line_items": [
      {
        "type": "line_item",
        "id": 482954,
        "name": "Standard Service Fee",
        "description": "Local non-rush service fee",
        "unit_cost": "75.0",
        "quantity": "1.0",
        "tax_rate": "0.0",
        "tax_amount": "0.0",
        "subtotal": "75.0",
        "total": "75.0",
        "updated_at": "2024-05-13T10:07:21-06:00",
        "created_at": "2024-05-13T10:07:21-06:00"
      },
      {
        "type": "line_item",
        "id": 482960,
        "name": "Multiple Attempt Fee",
        "description": "Additional fee for several attempts",
        "unit_cost": "10.0",
        "quantity": "1.0",
        "tax_rate": "0.0",
        "tax_amount": "0.0",
        "subtotal": "10.0",
        "total": "10.0",
        "updated_at": "2024-05-21T10:07:21-06:00",
        "created_at": "2024-05-21T10:07:21-06:00"
      }
    ],
    "payments": []
  }
}

Webhooks

POST /api/webhooks

Creates a webhook for the account. The webhook will be triggered when the specified event(s) occur. See the Webhook Documentation for more information on the functionality of webhooks themselves. The response will include a secret_key that you should use to verify the authenticity of webhook payloads, as described in the Webhook Authentication Documentation.

Attribute Description
type * MUST be equal to "webhook". Any other value causes a 409 CONFLICT error.
name * The name displayed in the webhook management interface for this webhook.
client_reference_key This key will ensure you don't create the same webhook twice. If you send a request with the same client_reference_key as a previous request, you will receive an error. HOWEVER, if you also set update_if_exists to true, then your webhook will be UPDATED with the new params, instead of creating a duplicate webhook. For exammple, if you sent this payload first:
{
  "type": "webhook",
  "name": "My Webhook",
  "client_reference_key": "my-webhook",
  "update_if_exists": true,
  "target_url": "https://example.com/webhook",
  "events": ["jobs:created"]
}
But later wanted to register additional events, you could send this payload:
{
  "type": "webhook",
  "name": "My Webhook",
  "client_reference_key": "my-webhook",
  "update_if_exists": true,
  "target_url": "https://example.com/webhook",
  "events": ["jobs:created", "jobs:updated", "invoices:created"]
}
This will update your original webhook with the new events, it will NOT create a new duplicate webhook. Omitting the client_reference_key will allow you to create multiple webhooks with the same params.
update_if_exists Defaults to false. If set to true, and a webhook with the same client_reference_key already exists, the existing webhook will be updated with the new params. When this is false, attempting to create a webhook with the same client_reference_key as an existing webhook will result in a 422 Unprocessable Entity error.
target_url * The URL that the webhook will POST to when the event is triggered.
batch_interval_in_seconds The minimum number of seconds between webhook events being fired. Webhook events will be batched up as explained in Webhook Batching, and this number determines how often that will occur. (between 0 and 120 seconds). Defaults to 60 seconds.
events * An array of event names that you want to subscribe this webhook to. The available events are:

jobs:created, jobs:updated, jobs:deleted, attempts:created, attempts:updated, attempts:deleted, notes:created, notes:updated, notes:deleted, attachments:created, attachments:updated, attachments:deleted, documents:created, documents:updated, documents:deleted, affidavits:signed, invoices:created, invoices:updated, invoices:issued, invoices:deleted, server_invoices:created, server_invoices:updated, server_invoices:deleted

Go to the Webhook Events Documentation for more details about each of these different events.

Example:

{
  "events": ["jobs:created", "jobs:updated", "invoices:created"]
}
enabled A boolean value that determines if the webhook is enabled or not. If not provided, it will default to true.

Example Request:

curl https://www.servemanager.com/api/webhooks \
  -u YXStULZfPGhUQndar3dVkQ: \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "webhook",
      "name": "My Webhook",
      "target_url": "https://example.com/webhook",
      "client_reference_key": "my-webhook",
      "update_if_exists": true,
      "events": ["jobs:created", "jobs:updated", "invoices:created"]
    }
  }'

Example Response:

{
  "data": {
    "type":"webhook",
    "id":"369aae1d-5f1f-4c19-8671-74af2f44a14d",
    "name":"My Webhook",
    "target_url":"https://example.com/webhook",
    "batch_interval_in_seconds":60,
    "client_reference_key": "my-webhook",
    "enabled":true,
    "events":["jobs:created","jobs:updated","invoices:created"],
    "secret_key":"wVCznzpLkFXiWYsHZtMBoxT2"
  }
}

PUT /api/webhooks/:id

Updates an existing webhook

Normally it is suggested you just use the client_reference_key and update_if_exists fields in the POST request to update a webhook, However, this endpoint will also update an existing webhook when given the id of that webhook (returned in the response when it was created).

Attributes allowed here are identical to those found in the Create Webhook endpoint, except update_if_exists will be ignored. This endpoint ALWAYS updates. All attributes except type are optional, omitted attributes will remain the same, changed attributes will update the params on the existing webhook.

Example Request:

curl https://www.servemanager.com/api/webhooks/369aae1d-5f1f-4c19-8671-74af2f44a14d \
  -X PUT \
  -u YXStULZfPGhUQndar3dVkQ: \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "webhook",
      "client_reference_key": "my-webhook-updated",
      "events": ["affidavits:signed"]
    }
  }'

Webhooks

Webhooks are powerful mechanisms built into ServeManager which allow an endpoint of your choosing to receive automatic, near-immediate payload updates occurring in your ServeManager account.

Webhook Interface

Webhooks can be configured in your ServeManager account by going to
My AccountSettingsManage Webhooks

You can make multiple webhook configurations that act independently of one another, as well as sending to different endpoints.

Webhook Options

Configurable options set within ServeManager that allow you to control the below webhook settings.

Option Description
Webhook Name

The name of the webhook configuration for your own reference. It should be descriptive of the webhook's purpose.

This name also appears in the payload sent to your endpoint.

Endpoint

The full URL where you want job update payloads to be sent.

This is the receiving side of the webhook, the destination where you need information sent. This URL should be found via the service or site you are using.

Batch Interval

Defines how often the webhook will send information to your endpoint. If this is set to 60 seconds (the default), then webhook events will be batched up over the course of 60 seconds, and send in a single payload to your endpoint. See Webhook Batching Documentation for a more detailed explanation of the batching process.

Enabled Simply turns your webhook on and off from sending information to the chosen endpoint.
Subscribed Events

The different kinds of events/actions within ServeManager that can send information via webhooks. You can choose one or more to send with a single webhook configuration. Only selected events will trigger a webhook.

You can see a list of available events in Webhook Payloads.

Webhook Overview

After saving a webhook, the basic information for all of your webhooks is available in the main interface.

Column Name Description
Name / Link

Clicking the webhook name will allow you to see all payloads sent by this webhook, as well as any pending payloads.

Events The number of events that this webhook has captured thus far.
Secret

An automatically generated secret key. This key is used by your endpoint to authenticate the webhook as legitimate and sent by ServeManager.

Please see the documentation on Authenticating Requests for more information about how to utilize this secret key to authenticate that requests sent to your endpoint are actually being sent by ServeManager.

Batching

Webhooks are sent periodically based on the batching interval (60 seconds by default). As updates to jobs occur, the events are collected, queued, and submitted in a single payload when the interval time is reached.

The webhook payload will contain a collection of jobs where an event/action took place. See Webhook Payloads for details about webhook payloads.

Authenticating Requests

Webhook payloads include a custom header when they reach your endpoint named X-SM-HMAC-SHA256. This header includes a signed hash verifying any given webhook payload originated from your ServeManager account and was not falsified by a third party.

This header and its corresponding signature comes in the following format:

x-sm-hmac-sha256=4UtWp1PHwF+VnIvzg0nVQpDq9BqMbLTAhJu5IWN0hUo=

The value of this header is a signed hash that you need to compare against to verify the request.

Verifying Payload

To verify the payload, take the following steps:

  1. Take the entire JSON payload body, and Base64 encode it, this is now the hashed_payload.
    • Ruby: Base64.strict_encode64("full webhook payload json")
    • JavaScript: btoa("full webhook payload json")
  2. Copy your webhook secret key (found on your ServeManager webhook overview page).
  3. Using the shared secret key for your webhook, apply the HMAC-SHA256 signing algorithm to the hashed_payload.
  4. Base64 encode the result once more. This should give you an alphanumeric signature that is identical to the signature found in the x-sm-hmac-sha256 header.
  5. Full Ruby Example:
    def verify_request(request, secret_key)
      auth_value = request.headers["X-SM-HMAC-SHA256"]
    
      result = Base64.strict_encode64(
        OpenSSL::HMAC.digest(
          "sha256",
          secret_key,
          Base64.strict_encode64(request.raw_post)
        )
      )
    
      auth_value == result
    end
  6. Full NodeJS Example:
    var CryptoJS = require("crypto-js");
    
    function calculateSignature(payloadBodyString, secretKey) {
      var hashedPayload = btoa(payloadBodyString);
      var hash = CryptoJS.HmacSHA256(hashedPayload, secretKey);
      return CryptoJS.enc.Base64.stringify(hash);
    }
    
    

Webhook Payloads

Every payload sent by a webhook comes in two parts:

  1. Webhook metadata
  2. Data about the updated object

Used our API before?

The job subscribed events webhook payload data is similar to the jobs payload API data. Therefore, you can use the same parsing to handle both webhooks and API.

The note subscribed events webhook payload data is structured separately from jobs, as note details are not included in job API requests. "Job note" webhook events include data that a notes API request would return.

The payload object will have one additional key, webhook_events, that details exactly what event(s) triggered the webhook in the first place.

The following table explains what each webhook_event's different attributes mean.

Attribute Name Description
type The exact object that was created, updated, or deleted. This may be different from the name of the event itself. For instance, if a job address is updated or added, the type is "address", but the event is "jobs:updated".
id The id of the object that was created, updated, or deleted. This corresponds to the id of the "type" object that was modified above.
event This is the exact webhook event that was triggered, from your webhook configuration. See the tables below for the lists of possible payload events.
event_reference A unique event reference id that can be used for troubleshooting.
action An event description that is either "create", "update", or "delete". It indicates the action taken on the "type" object. If an address was created, this would be "create", if the city on an address was edited, this would be "update".
changed For the "update" action, this is an array of attributes that were modified. This may include some internal attribute names that are unfamiliar, and some may seem redundant.
created_at The timestamp of when the event occurred.

Job Payload Events

Configurable events/actions for every job that you can choose to trigger a webhook, and will contain a full job payload object.

Event Name Event Description Example webhook_event
jobs:created A new job was created or shared with you.
{
  "type": "address",
  "id": 368439,
  "event": "jobs:updated",
  "event_reference": "010faae8-f203-4821-a83e-3ba6cfd8cdf5",
  "action": "create",
  "changed": [],
  "created_at": "2023-07-19T15:23:40-06:00"
}
jobs:updated A new client or server was assigned, job attributes were edited (status, due date, etc), recipient or address information was updated, or the job was archived.
jobs:deleted A job was deleted from the system.
attempts:created A new attempt was made, or shared with you.
{
  "type": "attempt",
  "id": 613317,
  "event": "attempts:updated",
  "event_reference": "263f5716-9aa9-45f8-9fb7-3ab19bf9a1ac",
  "action": "update",
  "changed": [
    "description"
  ],
  "created_at": "2023-07-20T15:19:23-06:00"
}
attempts:updated An attempt or file uploads on an attempt were updated.
attempts:deleted An attempt was deleted, or unshared with you.
attachments:created A file was uploaded to a job, or an upload was shared with you. (File uploads on attempts will trigger attempts:updated).
{
  "type": "attachment",
  "id": 551916,
  "event": "attachments:deleted",
  "event_reference": "816ee116-7eea-4f12-819d-37ca2e5f5a41",
  "action": "delete",
  "changed": [],
  "created_at": "2023-07-20T15:24:05-06:00"
}
attachments:updated A file on a job was edited.
attachments:deleted A file on a job was removed, or unshared with you.
documents:created An affidavit document was added to a job, or shared with you.
{
  "type": "document",
  "id": 1594425,
  "event": "affidavits:signed",
  "event_reference": "c7bffb62-bbf4-4f38-a359-d7cd1bc6e4ee",
  "action": "update",
  "changed": [
    "body",
    "electronic_signature_user_id",
    "electronic_signature_signed_at",
    "electronic_signature_user_agent",
    "electronic_signature_ip"
  ],
  "created_at": "2023-07-20T15:27:19-06:00"
}
documents:updated An affidavit document was edited.
documents:deleted An affidavit document was deleted, or unshared with you.
affidavits:signed An affidavit document was signed, or an uploaded attachment was flagged as a signed affidavit.
invoices:created An invoice was added to your job, for which your client should complete payment.
{
  "type": "invoice",
  "id": 2269207,
  "event": "server_invoices:created",
  "event_reference": "64e42a06-3921-4287-a8b2-5e15c86c9359",
  "action": "update",
  "changed": [
    "issued_on",
    "token",
    "last_issued_at"
  ],
  "created_at": "2023-07-20T16:12:01-06:00"
}
invoices:updated An invoice on your job was updated. Line items, payments, terms, or the issued date was changed.
invoices:issued An invoice "Issued On" date was set. When this event is triggered, an invoices:created or invoices:updated event will also be triggered.
invoices:deleted An invoice was deleted from your job.
server_invoices:created An invoice that your collaborating process server issued is now visible.
server_invoices:updated An invoice from your server was updated.
server_invoices:deleted An invoice from your server was deleted, or the issued date removed.

Note Payload Events

Configurable events/actions for every note that you can choose to trigger a webhook, and will only contain a note object in the data, since the regular job payload does not currently contain job note information.

Event Name Event Description Example webhook_event
notes:created A note on a job was created, or shared with you.
{
  "type": "note",
  "id": 1962368,
  "event": "notes:created",
  "event_reference": "3a8bd7ae-b77d-48b3-819d-7ffe8824f311",
  "action": "create",
  "changed": [],
  "created_at": "2023-07-20T16:18:07-06:00"
}
notes:updated A note on a job was edited.
notes:deleted A note on a job was deleted, or unshared from you.

Example Payload

{
  "meta": {
    "webhook_id": "84ca113a-a28e-47c4-86ba-6bab77b92728",
    "webhook_name": "My test hook",
    "reference": "dcb74aad-5c01-46f2-bfd3-1b1827341609",
    "created_at": "2023-07-20T16:18:07-06:00",
    "event_count": 12,
    "target_url": "https://webhook.site/c025f1ee-f751-45a7-a09d-b87dcf75ce6a",
    "account_id": 270207,
    "delivered_at": "2023-07-20T16:19:10-06:00"
  },
  "links": {
    "jobs": "http://localhost:3000/api/jobs?q=jobs%3A3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689%2C3679689"
  },
  "data": [
    {
      "links": {},
      "type": "note",
      "id": 1962368,
      "label": "Making a note",
      "body": "this is a note i'm making",
      "job_id": 736182,
      "updated_at": "2023-07-20T16:18:06-06:00",
      "created_at": "2023-07-20T16:18:06-06:00",
      "user_id": 4476652,
      "created_by": "Nathan Benes",
      "visibility": [
        "server"
      ],
      "shared_from": null,
      "emailed_to": [],
      "webhook_events": [
        {
          "type": "note",
          "id": 1962368,
          "event": "notes:created",
          "event_reference": "3a8bd7ae-b77d-48b3-819d-7ffe8824f311",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:07-06:00"
        }
      ]
    },
    {
      "links": {
        "self": "http://localhost:3000/api/jobs/736182"
      },
      "type": "job",
      "id": 736182,
      "servemanager_job_number": "3679689",
      "archived_at": null,
      "job_status": null,
      "service_status": "Served",
      "client_job_number": "",
      "service_instructions": null,
      "due_date": null,
      "rush": false,
      "updated_at": "2023-07-20T16:18:55-06:00",
      "created_at": "2023-07-20T16:11:19-06:00",
      "recipient": null,
      "created_by_id": 4476671,
      "duped_from_job_id": null,
      "duped_to_job_ids": [],
      "job_type_id": null,
      "mailing_date": null,
      "mailed_by_id": null,
      "mailing_location": null,
      "mailing_required": false,
      "client_company": null,
      "client_contact": null,
      "process_server_company": {
        "links": {
          "self": "http://localhost:3000/api/companies/858782"
        },
        "type": "company",
        "id": 858782,
        "name": "Acme Process Serving",
        "collaborating": true,
        "collab_status": "collaborating"
      },
      "process_server_contact": {
        "id": 981430,
        "first_name": "Kanisha",
        "last_name": "Will",
        "title": null,
        "email": "[email protected]",
        "phone": null,
        "license_number": null,
        "license_expiration": null,
        "dob": null,
        "primary": true,
        "created_at": "2023-07-20T12:38:33-06:00",
        "updated_at": "2023-07-20T12:38:33-06:00"
      },
      "employee_process_server": null,
      "court_case": null,
      "invoice": null,
      "process_server_invoice": {
        "type": "invoice",
        "id": 2269207,
        "balance_due": "0.0",
        "issued_on": "2023-07-20",
        "total_paid": "0.0",
        "total": "0.0",
        "terms": "Thanks for your business. Please pay the \"Balance Due\" within 21 days.",
        "paid_on": null,
        "job_id": 736181,
        "token": "RYWl8ZcWzVC5HoZ4rVwBwA",
        "taxes_enabled": false,
        "last_issued_at": "2023-07-20T16:11:44-06:00",
        "updated_at": "2023-07-20T16:11:44-06:00",
        "created_at": "2023-07-20T16:11:32-06:00",
        "client_id": 858783,
        "servemanager_job_number": 3679689,
        "pdf_download_url": "http://localhost:3000/api/v2/invoices/2269207/download",
        "line_items": [
          {
            "type": "line_item",
            "id": 2576025,
            "name": "This is an invoice line",
            "description": "Duuuude",
            "unit_cost": "0.0",
            "quantity": "1.0",
            "tax_rate": "0.0",
            "tax_amount": "0.0",
            "subtotal": "0.0",
            "total": "0.0",
            "updated_at": "2023-07-20T16:11:32-06:00",
            "created_at": "2023-07-20T16:11:32-06:00"
          }
        ],
        "payments": []
      },
      "addresses_count": 1,
      "addresses": [
        {
          "type": "address",
          "id": 368437,
          "label": "",
          "address1": "3739 Banyan Ct",
          "address2": "",
          "city": "Loveland",
          "state": "CO",
          "postal_code": "80538",
          "county": null,
          "lat": 40.4299,
          "lng": -105.09311,
          "created_at": "2023-07-20T16:18:51-06:00",
          "updated_at": "2023-07-20T16:18:52-06:00",
          "primary": true
        }
      ],
      "affidavit_count": 1,
      "documents": [
        {
          "type": "document",
          "id": 1594428,
          "title": "Nationwide Affidavit",
          "pdf_download_url": "http://localhost:3000/api/v2/documents/1594428/download",
          "signed": true,
          "created_at": "2023-07-20T16:18:55-06:00",
          "updated_at": "2023-07-20T16:18:55-06:00"
        }
      ],
      "document_to_be_served_count": 0,
      "document_to_be_served_total_page_count": 0,
      "documents_to_be_served": [],
      "misc_attachments_count": 2,
      "misc_attachments": [
        {
          "type": "misc_attachment",
          "id": 551917,
          "title": "summon_complaint.png",
          "affidavit": false,
          "signed": false,
          "updated_at": "2023-07-20T16:18:17-06:00",
          "created_at": "2023-07-20T16:18:17-06:00",
          "upload": {
            "file_name": "summon_complaint.png",
            "content_type": "image/png",
            "file_size": 6646,
            "record_type": "job",
            "record_id": 736182,
            "links": {
              "download_url": "https://servemanager-dev-storage.s3.amazonaws.com/0r0ct4u78sdikqz7xeivgv30zspm?response-content-disposition=attachment%3B%20filename%3D%22summon_complaint.png%22%3B%20filename%2A%3DUTF-8%27%27summon_complaint.png&response-content-type=image%2Fpng&X-Amz-Algorithm=SM-HMAC-SHA256&X-Amz-Credential=05NSPAYVZHNPZJ6W1F82%2F20230720%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230720T221910Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=63c8cbd1fcc9b42150fd5fdbddd8639f1c5f6946f3a36d1949860a66b311c704"
            }
          }
        },
        {
          "type": "misc_attachment",
          "id": 551918,
          "title": "sm_logo.svg",
          "affidavit": false,
          "signed": false,
          "updated_at": "2023-07-20T16:18:51-06:00",
          "created_at": "2023-07-20T16:18:51-06:00",
          "upload": {
            "file_name": "sm_logo.svg",
            "content_type": "image/svg+xml",
            "file_size": 4631,
            "record_type": "attempt",
            "record_id": 613440,
            "links": {
              "download_url": "https://servemanager-dev-storage.s3.amazonaws.com/e3yv0j1oes2eumwsf3x6erkfsl1b?response-content-disposition=attachment%3B%20filename%3D%22sm_logo.svg%22%3B%20filename%2A%3DUTF-8%27%27sm_logo.svg&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=SM-HMAC-SHA256&X-Amz-Credential=05NSPAYVZHNPZJ6W1F82%2F20230720%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230720T221910Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=62141b4eb3c4b9ddfded387238c5e1e4dc636aa79c170f707af549bc68c5eb0b"
            }
          }
        }
      ],
      "attempt_count": 1,
      "last_attempt_served_at": "2023-07-20T16:18:00-06:00",
      "last_attempt_served_at_timezone": "America/Denver",
      "attempts": [
        {
          "type": "attempt",
          "id": 613440,
          "job_id": 736182,
          "description": "New attempt",
          "lat": null,
          "lng": null,
          "serve_type": "Personal/Individual",
          "gps_timestamp": null,
          "device_timestamp": null,
          "gps_accuracy": null,
          "gps_heading": null,
          "gps_speed": null,
          "gps_altitude": null,
          "gps_altitude_accuracy": null,
          "gps_user_agent": null,
          "success": true,
          "created_at": "2023-07-20T16:18:51-06:00",
          "updated_at": "2023-07-20T16:18:51-06:00",
          "mobile_app_attempt": null,
          "attachments": [
            {
              "type": "attachment",
              "id": 551918,
              "title": "sm_logo.svg",
              "updated_at": "2023-07-20T16:18:51-06:00",
              "created_at": "2023-07-20T16:18:51-06:00",
              "upload": {
                "file_name": "sm_logo.svg",
                "content_type": "image/svg+xml",
                "file_size": 4631,
                "record_type": "attempt",
                "record_id": 613440,
                "links": {
                  "download_url": "https://servemanager-dev-storage.s3.amazonaws.com/e3yv0j1oes2eumwsf3x6erkfsl1b?response-content-disposition=attachment%3B%20filename%3D%22sm_logo.svg%22%3B%20filename%2A%3DUTF-8%27%27sm_logo.svg&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=SM-HMAC-SHA256&X-Amz-Credential=05NSPAYVZHNPZJ6W1F82%2F20230720%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230720T221910Z&X-Amz-Expires=1800&X-Amz-SignedHeaders=host&X-Amz-Signature=62141b4eb3c4b9ddfded387238c5e1e4dc636aa79c170f707af549bc68c5eb0b"
                }
              }
            }
          ],
          "servemanager_job_number": 3679689,
          "service_status": "Served",
          "server_name": "Kanisha Will",
          "served_at": "2023-07-20T16:18:00-06:00",
          "recipient_full_description": "Other: asdf",
          "mobile": false,
          "recipient": {
            "name": "Dudeface",
            "age": "",
            "ethnicity": "",
            "gender": "",
            "weight": "",
            "height1": "",
            "height2": "",
            "hair": "",
            "relationship": "",
            "eyes": "",
            "description": "asdf",
            "email": "",
            "phone": ""
          },
          "address": {
            "type": "address",
            "id": 368437,
            "label": "",
            "address1": "3739 Banyan Ct",
            "address2": "",
            "city": "Loveland",
            "state": "CO",
            "postal_code": "80538",
            "county": null,
            "lat": 40.4299,
            "lng": -105.09311,
            "created_at": "2023-07-20T16:18:51-06:00",
            "updated_at": "2023-07-20T16:18:52-06:00",
            "primary": true
          },
          "process_server": null,
          "visibility": [
            "server"
          ],
          "shared_from": null,
          "emailed_to": []
        }
      ],
      "custom": {},
      "quoted_supplier_cost_id": null,
      "quoted_page_count": null,
      "quoted_retail_price": null,
      "quoted_percent_discount": null,
      "client_transaction_ref": null,
      "webhook_events": [
        {
          "type": "misc_attachment",
          "id": 551917,
          "event": "attachments:created",
          "event_reference": "4ebb67cd-8b5f-4116-9359-581320100bcc",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:17-06:00"
        },
        {
          "type": "address",
          "id": 368437,
          "event": "jobs:updated",
          "event_reference": "3b93d59c-9531-43cd-a86d-280505abad10",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "attachment",
          "id": 551918,
          "event": "attempts:updated",
          "event_reference": "12c77d0f-b262-4930-9266-67b2509b8b99",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "attempt",
          "id": 613440,
          "event": "attempts:created",
          "event_reference": "9c50eae4-b931-48dd-8a1d-bcfe5a79af88",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "job",
          "id": 736182,
          "event": "jobs:updated",
          "event_reference": "90b753b0-3cf2-4eee-890e-3f1abee3dba3",
          "action": "update",
          "changed": [
            "last_attempt_served_at",
            "last_attempt_served_at_timezone"
          ],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "job",
          "id": 736182,
          "event": "jobs:updated",
          "event_reference": "0763d0fe-dbfa-4972-b6a3-51792ca5182c",
          "action": "update",
          "changed": [
            "attempt_count"
          ],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "job",
          "id": 736182,
          "event": "jobs:updated",
          "event_reference": "3606801a-5863-45f4-9bf7-9f9b9385e856",
          "action": "update",
          "changed": [
            "status"
          ],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "address",
          "id": 368437,
          "event": "jobs:updated",
          "event_reference": "bdc35a1e-cb8a-42fa-885b-8a5faf8b8c62",
          "action": "update",
          "changed": [
            "primary"
          ],
          "created_at": "2023-07-20T16:18:54-06:00"
        },
        {
          "type": "document",
          "id": 1594428,
          "event": "documents:created",
          "event_reference": "40039c6a-efd1-401a-9990-f00cd80b70e7",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:59-06:00"
        },
        {
          "type": "document",
          "id": 1594428,
          "event": "affidavits:signed",
          "event_reference": "8ee75506-d515-4266-8f9e-08e664c3a3f1",
          "action": "create",
          "changed": [],
          "created_at": "2023-07-20T16:18:59-06:00"
        },
        {
          "type": "job",
          "id": 736182,
          "event": "jobs:updated",
          "event_reference": "c662a031-3445-47c8-9bc7-4f0be2791180",
          "action": "update",
          "changed": [
            "affidavit_count",
            "signed_affidavit"
          ],
          "created_at": "2023-07-20T16:19:00-06:00"
        }
      ]
    }
  ]
}