Skip to content

clients.md

Latest commit

 

History

History
230 lines (179 loc) · 6.52 KB

clients.md

File metadata and controls

230 lines (179 loc) · 6.52 KB

Clients

Getting clients

You can list clients by making a GET request to:

  • /api/clients for a list of all clients
  • /api/clients?where=active=true for a list of active clients
  • /api/clients?where=active=false for a list of archived clients

Example of response:

{
   "clients": [
      {
         "id": 1,
         "name": "NBC Universal, Inc.",
         "address": "1277 Fairfax Drive",
         "city": "New York",
         "state": "NY",
         "postal_code": "07302",
         "country": "US",
         "phone": "646-772-0207",
         "fax": "646-772-0207",
         "email": "sales@nbc.com",
         "website": "www.nbc.com",
         "image": "https://app.paymoapp.com/assets/1/clients/fd1fc0c388bbd7aff03a6be5aa5f8945.png",
         "fiscal_information": "",
         "active": true,
         "created_on": "2013-06-26T12:07:44Z",
         "updated_on": "2014-08-04T12:12:13Z"
      },
      {
         "id": 2,
         "name": "Best Buy Co., Inc.",
         "address": "4965 North Street\n",
         "city": "Richfield",
         "state": "Minnesota",
         "postal_code": "84116",
         "country": "US",
         "phone": "716-592-1227",
         "fax": "716-592-1227",
         "email": "sales@bestbuy.com",
         "website": "www.bestbuy.com",
         "image": "https://app.paymoapp.com/assets/1/clients/103bcf5e11fa4f261151e2a3b69be269.png",
         "fiscal_information": "",
         "active": true,
         "created_on": "2013-06-26T12:07:44Z",
         "updated_on": "2014-08-13T12:35:48Z"
      }
   ]
}

You can also include related content when listing clients.

Getting a client

To get the client info, make a GET request to:

  • /api/clients/[CLIENT_ID]

Example response:

{
   "clients": [
      {
         "id": 1,
         "name": "NBC Universal, Inc.",
         "address": "1277 Fairfax Drive",
         "city": "New York",
         "state": "NY",
         "postal_code": "07302",
         "country": "US",
         "phone": "646-772-0207",
         "fax": "646-772-0207",
         "email": "sales@nbc.com",
         "website": "www.nbc.com",
         "image": "https://app.paymoapp.com/assets/1/clients/fd1fc0c388bbd7aff03a6be5aa5f8945.png",
         "fiscal_information": "",
         "active": true,
         "created_on": "2013-06-26T12:07:44Z",
         "updated_on": "2014-08-04T12:12:13Z"
      }
   ]
}

You can also include related content when getting a client.

Creating a client

To create a client, make a POST request to:

  • /api/clients

with the request body containing the new client info, as in the example below:

{
    "name": "Smith and Sons",
    "email": "office@smithandsons.com"
}

If successful, the response will return 201 Created. The response header Location will contain a link for the new client. The response body will contain the new client info as in the Getting a client section.

Required fields

When creating a client: name.

Updating a client

To update an existing client, make a POST or PUT request to:

  • /api/clients/[CLIENT_ID]

with the request body containing the updated info. You can send only the changed fields.

Example of request body if you want to change the client name and address:

{
    "name": "Smith and Sons Ltd.",
    "address": "2000 Salmon Creek Lane\nJuneau, AK 99801"
}

The response will return 200 OK and will contain the updated client info as in the Getting a client section.

Archiving or activating a client

To archive a client, make an update request with the following body:

{
    "active": false
}

To activate, send a true value.

Adding a client logo

To add a client logo image, make a POST request to:

  • /api/clients/[CLIENT_ID]

The request content-type should be multipart-form-data and the file field name equal to image. Here's an example using curl command line:

curl -u email:password
  -H 'Accept: application/json'
  -F "image=@logo.png"
  https://app.paymoapp.com/api/clients/12345

Accepted image file formats are: JPEG, PNG, GIF.

The logo image of a client can be added when creating the client. In that case, all the client fields should be send in multipart-form-data format together with the file.

Deleting a client

To delete a client, make a DELETE request to:

  • /api/clients/[CLIENT_ID]

If successful, the response will have a 200 OK status code.

Warning

Deleting a client will also delete all info related to that client: projects, task and task lists, time entries from those projects!

The client object

A client object has the following attributes:

Attribute Type Description
id integer (read-only) Unique client identifier
name text Client name
address text Street address
city text City name
postal_code text Postal code
country text Country name
state text State or Region name
phone text Phone number
fax text Fax number
email email Email address
website url Website address
active boolean (read-only) If true the client is active, otherwise the client is archived.
fiscal_information text Fiscal information. It is used in invoice headers to display client details.
created_on datetime (read-only) Date and time when the client was created
updated_on datetime (read-only) Date and time when the client was last updated
image url Client logo image URL
image_thumb_large url (read-only) Client logo image large size thumbnail URL
image_thumb_medium url (read-only) Client logo image medium size thumbnail URL
image_thumb_small url (read-only) Client logo image small size thumbnail URL

Dependent objects

The following object types can be used in includes:

Object type Include key Relationship
Client contact clientcontacts child
Project projects child
Invoice invoices child
Recurring invoice profile recurringprofiles child