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.

Authenication

GET an existing resource

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. If you're willing to share a basic example in your language, we'd love to see it!

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 reource URLs, expected headers and data payloads.

Authentication

Contact us for an API key. Keep your API key secret. Never email or send it 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, and GET methods.

HTTP header Content-Type: application/jsonmust be set when performing a POST, PUT, or 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, or
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

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.

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 distinquishes between two types of uploads: documents to be served and miscelaneous attachments. Documents to be served is intended only for service documents. Miscelaneous 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. PUT the document data to that 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.

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.

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.

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.

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, but has URL-escaped it.

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:

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)