Contents

Contacts

Brands need to keep up with their customers, whether those customers have scheduled a session or purchased the photos of a family member. They do this by managing contacts. Contacts can be attached to events, contracts, invoices, and more.

List a brand’s contacts

get
/studio/brand/{brandId}/contact

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Query Parameters

Property Description
filterAllBrands

Return all contacts across all brands for the studio.

filterBrandId

Filters a collection by brand identifier.

filterEventId

Filters a collection by event identifier.

filterTag

Filter contacts by those having all of the given tags.

page

The page of results to return.

rows

The number of rows to return on each page of results.

searchContactInfo

Search contacts by name or email address, with partial matching.

searchEmail

Search contacts by email address, with exact matching.

sortBy

Sort items in the collection by the given property.

sortType

The direction in which sorting should occur.

Header Parameters

Property Description
Accept

You may specify an Accept header to change the type of response, using content negotiation.

Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A collection of brand contacts.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

brandId write-only deprecated

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.

businessName nullable

The name for the business with which this contact is associated.

created read-only

The date on which this contact was created

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

refereeContacts read-only

Contacts that have been referred by this contact.

referringContact nullable read-only

The contact who referred this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

resourceCounts read-only
Property Description
numContracts

The number of contracts with which this contact is associated.

numEvents

The number of events with which this contact is associated.

numInvoices

The number of invoices with which this contact is associated.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The type of resource represented.

Alternate Response Body

When the Content-Type of the response is text/csv, the following properties will be available in the response body.

Properties
Example Response
"\"Contact ID\",Brand,\"First Name\",\"Last Name\",Name,Email,Phone,Business,\"Contact Third Party ID\",Birthday,Tags,Created,\"Address 1\",\"Address 2\",City,State,ZIP/postal,Country,\"Referred By\",\"Referred Contacts\",Galleries\n\"0cc2ff9f-7c7a-418f-bf1b-bfbfde277a0e\",\"Jones Photography\",Jane,Doe,\"Jane Doe\",jdoe@example.com,123-456-7890,\"Acme, Inc.\",\"AwABAgkOAQIDCgIABA8MCw\",1971-06-08,\"Customer, Vendor\",2016-06-13T21:51:07+00:00,\"123 Any St\",\"Suite 102\",Anytown,GA,30039,US,\"John Doe\",\"Helen Doe, Jake Smith\",\"Doe Wedding, Jim Doe Graduation\""

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/ContactCollection"
        }
      },
      "text/csv": {
        "example": "\"Contact ID\",Brand,\"First Name\",\"Last Name\",Name,Email,Phone,Business,\"Contact Third Party ID\",Birthday,Tags,Created,\"Address 1\",\"Address 2\",City,State,ZIP/postal,Country,\"Referred By\",\"Referred Contacts\",Galleries\n\"0cc2ff9f-7c7a-418f-bf1b-bfbfde277a0e\",\"Jones Photography\",Jane,Doe,\"Jane Doe\",jdoe@example.com,123-456-7890,\"Acme, Inc.\",\"AwABAgkOAQIDCgIABA8MCw\",1971-06-08,\"Customer, Vendor\",2016-06-13T21:51:07+00:00,\"123 Any St\",\"Suite 102\",Anytown,GA,30039,US,\"John Doe\",\"Helen Doe, Jake Smith\",\"Doe Wedding, Jim Doe Graduation\"",
        "schema": {
          "title": "Comma-separated values",
          "type": "string"
        }
      }
    },
    "description": "A collection of brand contacts."
  }
}

Create a contact

post
/studio/brand/{brandId}/contact

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

application/vnd.shootproof+json
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

brandId write-only deprecated

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.

businessName nullable

The name for the business with which this contact is associated.

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Contact"
      }
    }
  }
}

201 Created

The new contact.

Headers
Header Description
Location

The URL new contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

businessName nullable

The name for the business with which this contact is associated.

created read-only

The date on which this contact was created

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

refereeContacts read-only

Contacts that have been referred by this contact.

referringContact nullable read-only

The contact who referred this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

resourceCounts read-only
Property Description
numContracts

The number of contracts with which this contact is associated.

numEvents

The number of events with which this contact is associated.

numInvoices

The number of invoices with which this contact is associated.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "201": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "The new contact.",
    "headers": {
      "Location": {
        "description": "The URL new contact.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

List tags that may be applied to contacts

get
/studio/brand/{brandId}/contact/tag

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Query Parameters

Property Description
searchTagName

Search contact tags, with partial matching.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A list of tags for contacts.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
isInUse

Whether this tag is currently applied to any contacts.

name

The contact tag name.

type

The type of resource represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/List"
            },
            {
              "properties": {
                "items": {
                  "items": {
                    "properties": {
                      "isInUse": {
                        "description": "Whether this tag is currently applied to any contacts.",
                        "type": "boolean"
                      },
                      "name": {
                        "description": "The contact tag name.",
                        "example": "Event Coordinator",
                        "type": "string"
                      },
                      "type": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/Type"
                          },
                          {
                            "enum": [
                              "contact-tag"
                            ]
                          }
                        ]
                      }
                    },
                    "title": "Contact Tag",
                    "type": "object"
                  },
                  "title": "Contact Tag",
                  "type": "array"
                },
                "type": {
                  "enum": [
                    "contact-tag-collection"
                  ]
                }
              },
              "title": "Collection of Contact Tags"
            }
          ]
        }
      }
    },
    "description": "A list of tags for contacts."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Delete a contact

delete
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contactId required

The contact identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

204 No Content

The resource was successfully deleted.

409 Conflict

If the the contact is linked to an invoice or contract, then we will respond with a 409 Conflict response.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "204": {
    "$ref": "#/components/responses/deleteSuccess"
  },
  "409": {
    "content": {
      "application/problem+json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "description": "If the the contact is linked to an invoice or contract, then we will\nrespond with a `409 Conflict` response."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Get a contact

get
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contactId required

The contact identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

businessName nullable

The name for the business with which this contact is associated.

created read-only

The date on which this contact was created

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

refereeContacts read-only

Contacts that have been referred by this contact.

referringContact nullable read-only

The contact who referred this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

resourceCounts read-only
Property Description
numContracts

The number of contracts with which this contact is associated.

numEvents

The number of events with which this contact is associated.

numInvoices

The number of invoices with which this contact is associated.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "A contact."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Update a contact

put
/studio/brand/{brandId}/contact/{contactId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contactId required

The contact identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

A contact.

application/vnd.shootproof+json
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

brandId write-only deprecated

When creating a contact, a brandId may be provided to create the contact under a different brand.

This is deprecated in favor of using the other brand's contact collection resource to create contacts for the brand.

businessName nullable

The name for the business with which this contact is associated.

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Contact"
      }
    }
  },
  "description": "A contact.",
  "required": true
}

200 OK

The updated contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

businessName nullable

The name for the business with which this contact is associated.

created read-only

The date on which this contact was created

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

refereeContacts read-only

Contacts that have been referred by this contact.

referringContact nullable read-only

The contact who referred this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

resourceCounts read-only
Property Description
numContracts

The number of contracts with which this contact is associated.

numEvents

The number of events with which this contact is associated.

numInvoices

The number of invoices with which this contact is associated.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "The updated contact."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Send an email message to a contact

post
/studio/brand/{brandId}/contact/{contactId}/email

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contactId required

The contact identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

application/vnd.shootproof+json
Property Description
body

The message to include in the body of the email.

headline

The headline to use in the email body.

subject

The subject line for the email message.

type

The type of resource represented.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "allOf": [
          {
            "properties": {
              "buttonText": {
                "readOnly": true
              },
              "recipientEmails": {
                "readOnly": true
              }
            }
          },
          {
            "$ref": "#/components/schemas/StudioToClientEmail"
          }
        ]
      }
    }
  },
  "required": true
}

202 Accepted

On success, we respond with the contact to whom the email message was sent.

Headers
Header Description
Content-Location

The URL to the contact that is located in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
address required nullable

The address for this contact.

birthDate nullable

The date on which this contact was born.

businessName nullable

The name for the business with which this contact is associated.

created read-only

The date on which this contact was created

email

The email address for this contact.

firstName nullable

The first name for this contact.

id

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

lastName nullable

The last name for this contact.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name nullable

The full name for this contact.

notes nullable

Notes made by the studio about this contact.

phone nullable

The phone number for this contact.

refereeContacts read-only

Contacts that have been referred by this contact.

referringContact nullable read-only

The contact who referred this contact.

referringContactId nullable

The identifier for the contact who referred this contact.

resourceCounts read-only
Property Description
numContracts

The number of contracts with which this contact is associated.

numEvents

The number of events with which this contact is associated.

numInvoices

The number of invoices with which this contact is associated.

tags

Tags describing this contact.

thirdPartyId nullable

The identifier for this contact in the source system from which it originated.

type

The type of resource represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "202": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Contact"
        }
      }
    },
    "description": "On success, we respond with the contact to whom the email message was\nsent.",
    "headers": {
      "Content-Location": {
        "description": "The URL to the contact that is located in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

List recent activity for a contact

get
/studio/brand/{brandId}/contact/{contactId}/recent-activity

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contactId required

The contact identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

A list of recent activity for a contact.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
activityDate nullable

The date on which this activity took place.

activityType

Human-readable description of the type of activity.

customInvoiceId nullable

Identifier of the custom invoice related to this activity.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

relevantId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

type

The type of resource represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The type of resource represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/ContactRecentActivityCollection"
        }
      }
    },
    "description": "A list of recent activity for a contact."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}