Table of Contents

  1. Overview

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

  2. Troubleshooting

    1. Status Codes

  3. Resource Methods

    1. Account
    2. Employees
    3. Companies
    4. Court Cases
    5. Courts
    6. Jobs
    7. Notes
    8. Attempts

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.

The upload process involves two steps. First, include meta data about the documents in the documents_to_be_served_attributes and misc_attachments_attributes on the job create endpoint. Second, the job response will contain a publicly accessible URL: put_url. See the document upload example. This URL is a short-lived, publicly-accessible URL. Use it only for a single document upload; it will expire shortly after job create. Uploads should be done immediately after a job is created.

This process ensures web requests are not blocked by long-running uploads.

System Event Emails

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

Troubleshooting

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

Status Codes

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

Resource Methods

Account

Enumerated Account Attributes:

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

GET /api/account

Returns information about your account.

Example Request: 

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

Example Response: 

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

Employees

GET /api/employees

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

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

Example Request: 

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

Example Response: 

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

GET /api/employees/:id

Returns details about a specific employee

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

Example Response: 

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

Companies

Enumerated Company Attributes:

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

GET /api/companies

Returns an array of companies and details about them.

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

Available URL Parameter Filters:

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

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

Example Request: 

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

Example Response: 

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

POST /api/companies

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

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

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

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

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

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

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

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

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

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

Example Request: 

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

Example Response: 

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

    ],
    "email_addresses": [

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

PUT /api/companies/:id

Updates an existing company

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

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

Example Request: 

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

Court Cases

GET /api/court_cases

Returns an array of court cases on your account

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

Available URL Parameter Filters:

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

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

Example Request: 

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

Example Response: 

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

GET /api/court_cases/:id

Returns details about a single specific court case.

Example Request: 

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

Example Response: 

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

POST /api/court_cases

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

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

Example Request: 

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

Example Response: 

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

Courts

GET /api/courts

Returns an array of court locations on your account

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

Example Request: 

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

Example Response: 

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

GET /api/courts/:id

Returns details about a single specific court location

Example Request: 

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

Example Response: 

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

POST /api/courts

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

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

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

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

Example Request: 

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

Example Response: 

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

Jobs

Enumerated Job Attributes:

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

GET /api/jobs

Returns an array of jobs available for you

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

Available URL Parameter Filters:

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

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

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
      },
      "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
      },
      "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": [
        {
          "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"
        }
      ],
      "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,
            "links": {
              "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
            }
          }
        }
      ],
      "misc_attachments": [
        {
          "type": "misc_attachment",
          "id": 345956,
          "title": "Photo of Recipient",
          "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",
          "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
        }
      ],
      "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",
    "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
    },
    "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
    },
    "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": [
      {
        "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": null,
        "created_at": null,
        "updated_at": null
      }
    ],
    "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,
          "links": {
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
          }
        }
      }
    ],
    "misc_attachments": [
      {
        "type": "misc_attachment",
        "id": 345956,
        "title": "Photo of Recipient",
        "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",
        "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
      }
    ],
    "custom": {}
  }
}

POST /api/jobs

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

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

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

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

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

{
  "documents_to_be_served_attributes": [
    {
      "title":"Subpoena",
      "received_at":"2015-02-13T15:49:00.000-06:00",
      "file_name":"subpoena_file.pdf"
    }
  ]
}
documents_to_be_served_attributes['title'] The title of the document
documents_to_be_served_attributes['received_at'] The date and time that the document was received. Should match the datetime format specified in the Date Formatting section.
documents_to_be_served_attributes['file_name'] The filename of a file that is to be attached to the job. Note that if you want multiple electronic files attached, you MUST send multiple documents_to_be_served or misc_attachments nodes with one file_name each. The response will then include a put_url for each document_to_be_served that was created, which you should use to individually PUT files to so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. (See 'Document Upload' examples below)
misc_attachments_attributes

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

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

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

    ],
    "documents_to_be_served": [
      {
        "type": "document_to_be_served",
        "id": 214199,
        "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,
          "links": {
            "put_url": "https://PUT_URL_FROM_JOB_CREATE_RESPONSE",
            "download_url": "https://s3.amazonaws.com/EXPIRES_IN_5_MINUTES_DOWNLOAD_SOON"
          }
        }
      }
    ],
    "misc_attachments": [

    ],
    "attempts": [

    ],
    "custom": {}
  }
}

Example Document Upload Request 

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

PUT /api/jobs/:id

Updates an existing job

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

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

Example Request: 

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

Notes

POST /api/jobs/:job_id/notes

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

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

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

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

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

Attempts

Enumerated Attempt Attributes:

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

GET /api/attempts

Returns an array of attempts and details about them.

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

Example Request: 

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

Example Response: 

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

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

POST /api/jobs/:job_id/attempts

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

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

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

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

If this is present, address_id CANNOT be present.

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

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

{
  "attachments_attributes": [
    {
      "title":"Photo of Home",
      "file_name":"photo_of_home1.jpg"
    }
  ]
}
attachments_attributes['title'] The title of the attachment
attachments_attributes['file_name'] The filename of the attachment. Note that if you want multiple electronic files attached, you MUST send multiple attachment nodes with one file_name and title each. The response will then include a put_url for each file that was created, which you should use to individually PUT files to so they will be properly attached to the job. This put_url will be accessible for 1 hour after the job has been created. (See the document upload example.)
visibility

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

{
  "visibility": ["client"]
}

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

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