Cope Notes API Documentation

API Key Authentication

When given access to our API, we will provide you with two API Keys:

• Test API Key: To validate your implementation.
• Live API Key: To be used once your implementation is working properly.

Add Trial User

Endpoint

URL: api.copenotes.com/public/users/trial
Method: POST

Example Header

POST /public/users/trial HTTP/1.1
Host: api.copenotes.com
Authorization: <REPLACE_WITH_API_KEY>
Content-Type: application/json

Example Body

{
  "countryCode": 1, // integer
  "phone": "7175000000", // integer
  "ip": "1.1.1.1", // string, optional. Takes precedence over remote_addr if both are provided.
  "remote_addr": "192.168.1.1", // string, optional. Used as a fallback if ip is not provided.
  "timeZone": "America/Chicago" // string, optional. Required if neither ip nor remote_addr is provided.
   // ip, remote_addr, and timeZone: These are optional parameters, but at least one of them must be provided by the caller.
}

Example Responses

Success Response with Test API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "statusCode": 201,
  "message": "success. You are using the test API"
}

Success Response with Live API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "statusCode": 201,
  "message": "success. Trial user has been added"
}

Error Responses:

• General Error:

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Add Live User

Endpoint

URL: api.copenotes.com/public/users/add
Method: POST

Example Header

POST /public/users/add HTTP/1.1
Host: api.copenotes.com
Authorization: <REPLACE_WITH_API_KEY>
Content-Type: application/json

Example Body

{
  "countryCode": 1, // integer
  "phone": "7175000000", // integer
  "ip": "1.1.1.1", // string, optional. Takes precedence over remote_addr if both are provided.
  "remote_addr": "192.168.1.1", // string, optional. Used as a fallback if ip is not provided.
  "timeZone": "America/Chicago" // string, optional. Required if neither ip nor remote_addr is provided.
  // ip, remote_addr, and timeZone: These are optional parameters, but at least one of them must be provided by the caller.
}

Example Responses

Success Response with Test API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "statusCode": 201,
  "message": "success. You are using the test API"
}

Success Response with Live API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "statusCode": 201,
  "message": "success. Live user has been added"
}

Error Responses:

• Missing Required Fields:

{
  "error": "no timezone",
  "message": "IP Address or Timezone is required for subscription."
}

• Invalid or Missing Voucher Code:

{
  "statusCode": 400,
  "message": "Permission not granted. Contact Support."
}

• Voucher Expired or Depleted:

{
  "statusCode": 400,
  "message": "Permission not granted. Contact Support."
}

• User Already Active or Canceled:

{
  "statusCode": 400,
  "message": "User is already active or has been canceled."
}

• General Error:

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Restart a Stopped User

Endpoint

URL: api.copenotes.com/public/users/start
Method: POST

Example Header

POST /public/users/start HTTP/1.1
Host: api.copenotes.com
Authorization: <REPLACE_WITH_API_KEY>
Content-Type: application/json

Example Body

{
  "countryCode": 1, // integer
  "phone": "7175000000", // integer
  "ip": "1.1.1.1", // string, optional. Takes precedence over remote_addr if both are provided.
  "remote_addr": "192.168.1.1", // string, optional. Used as a fallback if ip is not provided.
  "timeZone": "America/Chicago" // string, optional. Required if neither ip nor remote_addr is provided.
  // ip, remote_addr, and timeZone: These are optional parameters, but at least one of them must be provided by the caller.
}

Example Responses

Success Response with Test API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "success. You are using the test API"
}

Success Response with Live API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "success. Live user has been started"
}

Error Responses:

• Missing Required Fields:

{
  "error": "no timezone",
  "message": "IP Address or Timezone is required for subscription."
}

• Invalid or Missing Voucher Code:

{
  "statusCode": 400,
  "message": "Permission not granted. Contact Support."
}

• Voucher Expired or Depleted:

{
  "statusCode": 400,
  "message": "Permission not granted. Contact Support."
}

• User Already Active:

{
  "statusCode": 400,
  "message": "User is already active."
}

• User is Canceled:

{
  "statusCode": 400,
  "message": "User is canceled."
}

• General Error:

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Stop Sending Messages to User

Endpoint

URL: api.copenotes.com/public/users/stop
Method: POST

Example Header

POST /public/users/stop HTTP/1.1
Host: api.copenotes.com
Authorization: <REPLACE_WITH_API_KEY>
Content-Type: application/json

Example Body

{
  "countryCode": 1, // integer
  "phone": "7175000000" // integer
}

Example Responses

Success Response with Test API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "statusCode": 201,
  "message": "success. You are using the test API"
}

Success Response with Live API Key:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "User stopped successfully"
}

Error Responses:

• Error Stopping User:

{
  "statusCode": 500,
  "message": "Failed to stop user subscription."
}

• User Validation Error:

{
  "statusCode": 400,
  "message": "User is not active or eligible for this action."
}

• General Error:

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Update User Profile

Endpoint

URL: api.copenotes.com/public/users/update
Method: PUT

Example Header

PUT /public/users/stop HTTP/1.1
Host: api.copenotes.com
Authorization: <REPLACE_WITH_API_KEY>
Content-Type: application/json

Example Body

{
  "newIntCode": 1, // string
  "newPhone": "7175000000", // string
  "newEmail": "user@example.com", // string
  "newTimeZone": "America/Chicago", // string
  "newStartTime": "09:00 AM", // string
  "newEndTime": "05:00 PM", // string
  "oldPhone": "17175000001" // string, full phone number including country code
}

Example Responses

Success Response with Test API Key:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "message": "success. You are using the test API"
}

Success Response with Live API Key:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "User profile updated successfully"
}

Error Responses:

• Error Updating User Profile:

{
  "statusCode": 500,
  "message": "Failed to update user profile."
}

• Duplicate Phone Number Error:

{
  "statusCode": 409,
  "message": "DUPLICATE_PHONE_NUMBER"
}

• General Error:

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

Webhooks

Events

Stop User

Description: The "Stop User" event is triggered when a user cancels their subscription and stops receiving messages.

Source Types: The source field in the webhook payload indicates how the event was triggered.

The following source types are currently supported: "sms": When a user cancels their subscription by sending a STOP text message. "dashboard": When a user cancels their subscription through the Cope Notes Dashboard.

Example Payload: A sample payload sent to the subscribed webhook URLs:

POST /webhook-url HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "fullPhone": "+13102569071",
  "source": "sms"
}