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:

Integrate and automate your projects from other CMS's or systems
Display or manage Project Map It data within an internal dashboard
Something else to make your job more efficient

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:

You'd like help discussing your strategy for integration
You're hitting limitations with the API
You have any other questions or feedback

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:

Authorization: Bearer your-api-token
Authorization: Basic your-api-token: (note the colon on the end)

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".
citystring	Example: "San Francisco".
streetstring	Example: "Lombard Street".
street_detailsstring	Example: "2nd Floor".
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.
surveySurveyAnswer[]	This will only be provided if the survey has been completed. Otherwise, this field will be an empty array.
surveyNamesstring[]	A set of Survey names associated 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.
surveyFlagstring	Determines whether or not this project can receive emails related to the surveys. One of "subscribed", "unsubscribed", or "blacklisted".
surveySentDate	Date which the survey for this project was sent.
surveyCompletedDate	Date which the survey for this project was completed.
activeboolean	Determines whether or not this project is public.
typestring	Determines what type of portfolio the project belongs to. One of "project", "member", or "tournament".
photoCountnumber	Indicates how many photos this project has associated.
member_infomemberInfo[]	Contains fields related to projects that belongs to type member.
tournament_infotournamentInfo[]	Contains fields related to projects that belongs to type tournament.

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

MemberInfo Type

phone_numbersstring[]	A list of contact numbers to store as a reference for this customer.
emailsstring[]	A list of contact emails to store as a reference for this customer.
socialMediastring[]	A list of social media links to store as a reference for this customer.
websitestring	The customers website.

TournamentInfo Type

hoststring	The tournaments hosting facility.
phone_numbersstring[]	A list of contact numbers to store as a reference for this tournament.
emailsstring[]	A list of contact emails to store as a reference for this tournament.
socialMediastring[]	A list of social media links to store as a reference for this tournament.
websitestring	The tournament's website.
genderstring	The gender division the tournament belongs to. One of "Boys", "Girls", or "Mixed".
age_levelstring	The age level division the tournament belongs to. Example "High School", "Middle School".
divisionsstring	The division the tournament belongs to. Example "AAA", "AA", "A", "B".
vendor_registrationstring	The link to the tournament's registration vendor.

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.
takenPicDateDate	Contains the Date on which the photo was taken. This will only be provided if the file it's an image. Otherwise, this field will match the creation date.
publishedBoolean	Determines whether or not this file is public.
original_filenameDate	The original name of the file. This will only be provided if the file it's an image and the name can be extracted from the file. Otherwise, this field will be null.
metaFileMeta	Contains the width and height of the file. This will only be provided if the file it's an image.
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://projectmapit.com/api/v1/project \
  -u your-api-key: \
  -d name="Awesome Project!" \
  -d city="San Francisco" \
  -d state="CA" \
  -d street="Lombard Street"

Arguments

statestring	required	This must be a valid state acronym such as "DC", "CA", or "NY".
citystring	required	Example: "San Francisco".
streetstring	required	Example: "Lombard Street".
street_detailsstring	optional	Example: "2nd Floor".
zipstring	optional	Example: "90210".
countrystring	optional	Example: "US".
namestring	optional	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.
activeboolean	optional	Determines whether or not this project is public.
typestring	optional	Determines what type of portfolio the project belongs to. One of "project", "member", or "tournament".
photoCountnumber	optional	Indicates how many photos this project has associated.
member_infomemberInfo[]	optional	Contains fields related to projects that belongs to type member.
tournament_infotournamentInfo[]	optional	Contains fields related to projects that belongs to type tournament.

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://projectmapit.com/api/v1/project/:projectId \
  -u your-api-key:

Arguments

projectIdstring

required

ID of project

Response

A project object will be returned if successful.

Update a project

PUT /api/v1/project

curl -X PUT \
  https://projectmapit.com/api/v1/project/:projectId \
  -u your-api-key: \
  -d name="New Project Name"

Arguments

statestring	required	This must be a valid state acronym such as "DC", "CA", or "NY".
citystring	required	Example: "San Francisco".
streetstring	required	Example: "Lombard Street".
street_detailsstring	optional	Example: "2nd Floor".
zipstring	optional	Example: "90210".
countrystring	optional	Example: "US".
namestring	optional	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.
surveyFlagstring	optional	Determines whether or not this project can receive emails related to the surveys. One of "subscribed", "unsubscribed", or "blacklisted".
activeboolean	optional	Determines whether or not this project is public.
typestring	optional	Determines what type of portfolio the project belongs to. One of "project", "member", or "tournament".
photoCountnumber	optional	Indicates how many photos this project has associated.
member_infomemberInfo[]	optional	Contains fields related to projects that belongs to type member.
tournament_infotournamentInfo[]	optional	Contains fields related to projects that belongs to type tournament.

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://projectmapit.com/api/v1/project/:projectId \
  -u your-api-key:

Arguments

projectIdstring

required

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

curl https://projectmapit.com/api/v1/project/:projectId/file\
    -u your-api-key: \
    -F 'file[]=@/path/to/some-file.jpg' \
    -F 'file[]=@/path/to/some-file-2.jpg'

Arguments

file[]file

required

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

oknumber

The value will always be 1 when submitted successfully.

Remove project photo

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

curl -X DELETE \
    https://projectmapit.com/api/v1/project/:projectId/file/:fileId \
    -u your-api-key:

Arguments

projectIdstring	required	The project's ID which the file is attached to.
fileIdstring	required	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://projectmapit.com/api/v1/project/:projectId/file/order \
    -d order="file-id-1" \
    -d order="file-id-2" \
    -d order="file-id-3" \
    -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://projectmapit.com/api/v1/projects \
  -u your-api-key:

Arguments

sstring	optional	Query string argument. Any string which a full index search is performed on.
pagestring	optional	Query string argument. A page number which contains a max of the specified limit.
limitstring	optional	Query string argument. Projects per page. The max is 100.
photosOnlyboolean	optional	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://projectmapit.com/api/v1/project/:projectId/send-survey \
    -u your-api-key:

Arguments

projectIdstring	required	The project's ID which the file is attached to.
commaDelimitedEmailsstring	optional	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.

Create a category

POST /api/v1/category

curl -X POST \
  https://projectmapit.com/api/v1/category \
  -u your-api-key: \
  -d name="Roofing" \
  -d parent="xxxxxx"

Arguments

namestring	optional	A name for the category. Default is "Untitled".
parentstring	optional	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://projectmapit.com/api/v1/category/:categoryId \
  -u your-api-key:

Arguments

categoryIdstring

required

ID of project

Response

A category object will be returned if successful.

Update a category

PUT /api/v1/category

curl -X PUT \
  https://projectmapit.com/api/v1/category/:categoryId \
  -u your-api-key: \
  -d name="New Category Name"

Arguments

namestring	optional	A name for the category. Default is "Untitled".
parentstring	optional	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://projectmapit.com/api/v1/category/:categoryId \
  -u your-api-key:

Arguments

categoryIdstring

required

Category ID.

Response

successnumber

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

GET /api/v1/categories?out=:format

curl https://projectmapit.com/api/v1/categories \
  -u your-api-key:

Arguments

outstring

optional

Query string argument. Allowed values:

flat - Returns a flat collection.

nested - Returns a nested collection by parent hierarchy.

Response

resultsCategory[]

A collection of category objects.

Users

Retrieve a user

GET /api/v1/current-user

curl https://projectmapit.com/api/v1/current-user \
  -u your-api-key:

Response

A basic user object will be returned if successful.

API Reference

Introduction

Authentication

Error Handling

Entity Types

Project Type

PhoneNumber Type

EmailAddress Type

SurveyAnswer Type

MemberInfo Type

TournamentInfo Type

File Type

FileMeta Type

FilePath Type

Category Type

Projects

Create a project

Arguments

Response

Retrieve a project

Arguments

Response

Update a project

Arguments

Response

Delete a project

Arguments

Response

Upload project photo

Arguments

Response

Remove project photo

Arguments

Response

Order project photos

Arguments

Response

List all projects

Arguments

Response

Send project survey

Arguments

Response

Categories

Create a category

Arguments

Response

Retrieve a category

Arguments

Response

Update a category

Arguments

Response

Delete a category

Arguments

Response

List all categories

Arguments

Response

Users

Retrieve a user

Response