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 that is accessible from a URL on the internet (preferred).
• Attaching a file that is only available as a local file, and needs to be uploaded.

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

• documents_to_be_served_attributes
• misc_attachments_attributes

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.

• Ensure Content-Type header is being set. POST and PUT requests will fail with status 406 if header is not Content-Type: application/json.
• Ensure POSTed data is JSON encoded. If data is url-encoded, status 409 may be returned.
• Ensure Basic auth header is base64 encoding the username:password value. All requests may fail with status 401 unauthorized otherwise.
• Inspect error responses. They may contain messages that help determine the issue.

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:

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,
    "can_receive_funds": true,
    "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

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:

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.

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.

{
  "addresses_attributes": [
    {
      "label":"Branch",
      "address1":"555 Example Street",
      "city":"Denver",
      "state":"CO",
      "postal_code":"80221",
      "primary":true
    }
  ]
}

{
  "email_addresses_attributes": [
    {
      "label":"Work",
      "email":"[email protected]"
    }
  ]
}

{
  "phone_numbers_attributes": [
    {
      "label":"Office",
      "number":"222-555-8879"
    }
  ]
}

{
  "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
    }
  ]
}

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:

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.

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

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

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"
    }
  }
}

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

{
  "address_attributes": {
    "address1":"555 Example Street",
    "address2":"Suite 329",
    "city":"Denver",
    "state":"CO",
    "postal_code":"80221"
  }
}

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:

GET /api/jobs

Returns an array of jobs available for you

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

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 ]

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

{
  "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"
  }
}

{
  "addresses_attributes": [
    {
      "label":"Branch",
      "address1":"555 Example Street",
      "city":"Denver",
      "state":"CO",
      "postal_code":"80221",
      "county":"Denver County",
      "primary":true
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "misc_attachments_attributes": [
    {
      "title":"Photo of Recipient",
      "file_name":"photo.png",
      "reference_number":"94HY39F"
    }
  ]
}

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:

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"}]}}'

POST /api/jobs/:id

Cancels an existing job.

Example Request (With Note):

curl https://www.servemanager.com/api/jobs/1234 -X POST \
  -u ${API_KEY}: \
  -H "Content-Type: application/json" \
  -d '{"data":{"type":"job","cancellation_note_label":"Job Closed","cancellation_note_body":"Job closed due to client request."}}'

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,
    "closed": true,
    "closed_at": "2015-03-18T10:19:27-04:00",
    "closed_by_id": 1234,
    "cancellation_note": {
      "id": 1234,
      "type": "note",
      "link": "https://www.servemanager.com/api/notes/1234"
    }
    "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": {}
  }
}

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.

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

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

{
  attachments_attributes: [
    {
      title: "Subpoena",
      file_name: "the_subpoena.pdf",
      affidavit: true,
      signed: false,
      upload_type: "document_to_be_served"
    }
  ]
}

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

{
  "visibility": ["client"]
}

{
  "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:

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

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

{
  "attachments_attributes": [
    {
      "title":"Photo of Home",
      "external_url":"http://www.example.com/house.jpg"
      "file_name":"photo_of_home1.jpg"
    }
  ]
}

{
  "visibility": ["client"]
}

{
  "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:

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.

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

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

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:

{
  "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.

{
  "type": "webhook",
  "name": "My Webhook",
  "client_reference_key": "my-webhook",
  "update_if_exists": true,
  "target_url": "https://example.com/webhook",
  "events": ["jobs:created"]
}

{
  "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"]
}

{
  "events": ["jobs:created", "jobs:updated", "invoices:created"]
}

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 Account → Settings → Manage 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.

Webhook Overview

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

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

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

• A single ServeManager job may have multiple events that trigger a webhook, but the job will only be listed a single time in the webhook payload. Please see details about the webhook_events below.

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

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.

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

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.

{
  "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"
}

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"
        }
      ]
    }
  ]
}