API Reference

Introduction

Welcome to the developer documentation for Project Map It. This API (Application Programming Interface) could be useful to you if you wish to do something such as:

We strive to make our system as flexible as possible and encourage you to reach out. Some reasons you want to contact us directly would be:

Authentication

The Project Map It API uses tokens to authenticate requests. You can view and manage your API tokens in the Project Map It Developer Dashboard. API tokens are used to authorize a request using one of the two HTTP headers:

You'll most likely use the Bearer token because it allows for cross-origin requests. We use the Basic protocol in the examples below because the syntax is simpler when making a curl request.

Error Handling

Project Map It uses conventional HTTP response codes to indicate the success or failure of an API request. A successful response will result in a 200. An unsuccessful response will result in a 4xx.

Along with a 4xx error code, an errors object will be returned which contains an array of one or more human-readable problems which occurred and a optional error code specific to the endpoint being requested.

{
    "code": 1000,
    "errors": [
        "Insufficient permissions"
    ]
}

Entity Types

Below are all of the various (JSON) object types which are returned by the Project Map It API.

Project Type

_idstring

The unique ID for the project.

statestring

This must be a valid state acronym such as "DC", "CA", or "NY". Used for geolocating.

citystring

Example: "San Francisco". Used for geolocating.

streetstring

Example: "Lombard Street". Used for geolocating.

namestring

A name for this project. By default, this name is for internal identification and not shown to the public.

categoriesstring[]

A set of category ID's to apply to this project.

surveyEmailsEmailAddress[]

The survey will be sent to these email addresses. 3 emails are allowed per project.

surveyPhoneNumbersPhoneNumber[]

A list of contact numbers to store as a reference for this project.

surveySurveyAnswer[]

This will only be provided if the survey has been completed. Otherwise, this field will be an empty array.

PhoneNumber Type

phonestring

A customer phone number for internal reference only.

EmailAddress Type

emailstring

A valid email address. If a survey is triggered, this is the email address which will be sent to.

SurveyAnswer Type

immutableboolean

A Project Map It system survey question which is guarenteed to be present for every project.

questionstring

The full question the customer was asked.

kindstring

One of "star", "boolean", or "text".

pubboolean

Determines whether or not this survey question is public.

answerstring

Star: "1", "2", "3", "4", or "5". Boolean: "1", "0". Text: "Customer input."

File Type

organizationstring

ID or organization.

referencestring

ID of the project which the file is associated to.

ordernumber

Number of photo order. This value will only be set if the image has been ordered.

createdDate

Date which record was created.

metaFileMeta

Date which record was created.

pathFilePath

Paths for file.

FileMeta Type

widthnumber

Width of image.

heightnumber

Height of image.

FilePath Type

smallstring

Full CDN URL to file.

largestring

Full CDN URL to file.

Category Type

_idstring

Category ID.

organizationstring

Organization ID.

parentstring

ID of the parent category.

namestring

Name of category.

createdDate

Date which record was created.

Projects

Create a project

POST /api/v1/project

curl -X POST \
  https://projectmap.it/api/v1/project \
  -u your-api-key: \
  -d name="Awesome Project!" \
  -d city="San Francisco" \
  -d state="CA" \
  -d street="Lombard Street"
Arguments
statestringrequired

This must be a valid state acronym such as "DC", "CA", or "NY". Used for geolocating.

citystringrequired

Example: "San Francisco". Used for geolocating.

streetstringrequired

Example: "Lombard Street". Used for geolocating.

zipstringoptional

Example: "90210".

namestringoptional

A name for this project. By default, this name is for internal identification and not shown to the public.

categoriesstring[]optional

A set of category ID's to apply to this project.

surveyEmailsEmailAddress[]optional

The survey will be sent to these email addresses if triggered. Otherwise, just used as internal reference.

surveyPhoneNumbersPhoneNumber[]optional

A list of contact numbers to store as a reference for this project.

Response

A project object will be returned if successful. The longitude and latitude will be generated automatically upon creation.

Retrieve a project

GET /api/v1/project/:projectId

curl https://projectmap.it/api/v1/project/:projectId \
  -u your-api-key:
Arguments
projectIdstringrequired

ID of project

Response

A project object will be returned if successful.

Update a project

PUT /api/v1/project

curl -X PUT \
  https://projectmap.it/api/v1/project/:projectId \
  -u your-api-key: \
  -d name="New Project Name"
Arguments
statestringrequired

This must be a valid state acronym such as "DC", "CA", or "NY". Used for geolocating.

citystringrequired

Example: "San Francisco". Used for geolocating.

streetstringrequired

Example: "Lombard Street". Used for geolocating.

zipstringoptional

Example: "90210".

namestringoptional

A name for this project. By default, this name is for internal identification and not shown to the public.

categoriesstring[]optional

A set of category ID's to apply to this project.

surveySurveyAnswer[]optional

The updated collection of survey answers. Warning: Any survey answers that aren't passed back will be removed.

surveyEmailsEmailAddress[]optional

The survey will be sent to these email addresses if triggered. Otherwise, just used as internal reference.

surveyPhoneNumbersPhoneNumber[]optional

A list of contact numbers to store as a reference for this project.

Response

A project object will be returned if successful. The longitude and latitude will be generated automatically if city, state or street is updated.

Delete a project

DELETE /api/v1/project/:projectId

curl -X DELETE \
  https://projectmap.it/api/v1/project/:projectId \
  -u your-api-key:
Arguments
projectIdstringrequired

ID of project

Response
successnumber

The value will always be 1. Otherwise, an error object will be returned.

Upload project photo

POST /api/v1/project/:projectId/file/upload

curl https://projectmap.it/api/v1/project/:projectId/file/upload \
    -u your-api-key: \
    -F 'file[]=@/path/to/some-file.jpg' \
    -F 'file[]=@/path/to/some-file-2.jpg'
Arguments
file[]filerequired

The file should follow the specifications of RFC 2388 (multipart/form-data protocol). Up to 5 files may be uploaded at a time. Supported formats are: jpeg, png, gif

Response

A project object will be returned if successful. The longitude and latitude will be generated automatically if city, state or street is updated.

Remove project photo

DELETE /api/v1/project/:projectId/file/upload

curl -X DELETE \
    https://projectmap.it/api/v1/project/:projectId/file/:fileId \
    -u your-api-key:
Arguments
projectIdstringrequired

The project's ID which the file is attached to.

fileIdstringrequired

The file's ID.

Response
oknumber

The value will always be 1 when removed successfully.

Order project photos

PUT /api/v1/project/:projectId/file/order

curl -X PUT \
    https://projectmap.it/api/v1/project/:projectId/file/:fileId/order \
    -d '{ "order": ["file-id-1", "file-id-2"] }' \
    -u your-api-key:
Arguments
orderstring[]required

An array of file ID's in the order they should be in.

Response
oknumber

The value will always be 1 when successful.

List all projects

GET /api/v1/projects?limit=5&page=1

curl https://projectmap.it/api/v1/projects \
  -u your-api-key:
Arguments
sstringoptional

Query string argument. Any string which a full index search is performed on.

pagestringoptional

Query string argument. A page number which contains a max of the specified limit.

limitstringoptional

Query string argument. Projects per page. The max is 100.

photosOnlybooleanoptional

If true, only projects with photos will be returned. Default is false.

Response
pagenumber

The current page.

pagesnumber

The total number of pages.

perPagenumber

The limit of projects per page.

resultsProject[]

A collection of project objects. Note that these are not expanded projects meaning that the categories field is just an array of ID's.

Send project survey

POST /api/v1/project/:projectId/send-survey

curl -X POST \
    https://projectmap.it/api/v1/project/:projectId/send-survey \
    -u your-api-key:
Arguments
projectIdstringrequired

The project's ID which the file is attached to.

commaDelimitedEmailsstringoptional

This argument is added for convenience. Any emails passed here will be attached to the project and used (along with any pre-existing) as recipients for the survey. Note: If the number of emails is more than 5 total for the project, an error will be returned.

Response
oknumber

The value will always be 1 when sent successfully.

Categories

Create a category

POST /api/v1/category

curl -X POST \
  https://projectmap.it/api/v1/category \
  -u your-api-key: \
  -d name="Roofing" \
  -d parent="xxxxxx"
Arguments
namestringoptional

A name for the category. Default is "Untitled".

parentstringoptional

The parent level category this category belongs to.

Response

A category object will be returned if successful.

Retrieve a category

GET /api/v1/category/:categoryId

curl https://projectmap.it/api/v1/category/:categoryId \
  -u your-api-key:
Arguments
categoryIdstringrequired

ID of project

Response

A category object will be returned if successful.

Update a category

PUT /api/v1/category

curl -X PUT \
  https://projectmap.it/api/v1/category/:categoryId \
  -u your-api-key: \
  -d name="New Category Name"
Arguments
namestringoptional

A name for the category. Default is "Untitled".

parentstringoptional

The parent level category this category belongs to.

Response

The full category object will be returned if successful.

Delete a category

DELETE /api/v1/category/:categoryId

curl -X DELETE \
  https://projectmap.it/api/v1/category/:categoryId \
  -u your-api-key:
Arguments
categoryIdstringrequired

Category ID.

Response
successnumber

The value will always be 1. Otherwise, an error object will be returned.

List all categories

GET /api/v1/categories

curl https://projectmap.it/api/v1/categories \
  -u your-api-key:
Arguments

None.

Response
resultsCategory[]

A collection of category objects.