Developers

Calendars

Fetch Calendars

Back to top

When your software wants to retrieve all PinkNotes Calendars for the logged-in user you must use the /api/getCalendars API.

//API Call to get all calendars

		https://www.pinknotes.com/api/getCalendars

//Generic Success Response From Server
//NOTE: When a Calendar is in a non-visible state, its items will not appear in https://www.pinknotes.com/api/getCalendarItemsAll

Fetch Calendar Events

Back to top

When your software wants to retrieve all PinkNotes Calendar Events visible to a user you must use the /api/getCalendarItemsAll API.

//API Call to get all calendar events

		https://www.pinknotes.com/api/getCalendarItemsAll?

		         _=[CURRENT TIMESTAMP]

		         &start=[STARTING TIMESTAMP]

		         &end=[ENDING TIMESTAMP]

//Generic Success Response From Server
//NOTE: When a Calendar is in a non-visible state, its items will not appear in https://www.pinknotes.com/api/getCalendarItemsAll

Add/Edit Calendar Events

Back to top

When your software wants to add a new event or edit an event in a PinkNotes Calendar you must use the /api/calendarSaveItem API.

API Field Description

Field	Values	Default	Required	Description
action	add or edit	add	Yes, to edit	If not specified will be set to add.
calendarId			Yes	ID number of calendar you want to add/edit in.
sDate			Yes	The date the event will start. Do not include time.
eDate			Yes	The date the event will end. Do not include time.
allDay	true or false	false		Set to true if the event is a full day event.
sTime			Yes, if allDay if false	The time the event will start.
eTime			Yes, if allDay is false	The time the event will end.
title			Yes	The title of the event. Max 100 chars.
description				The description of the event.
calEventId			Yes, only used when action is set to edit	The ID of the event you want to edit.
doRemind	true or false	false		When set to true a PinkNote will be sent to the user who created this event. The PinkNote will be sent the number of minutes before the event specified in reminderMinutes.
reminderMinutes			Yes, when doRemind is true	The number of minutes before the event a reminder PinkNote will be sent.
doRepeat	true or false	false		Use to put the same event in a calender multiple times.
repeatFreq	1 to 6		Yes, when doRepeat is true	Frequency at which the repeat event will be set.
repeatUnit	Hour, Day, Week, Month (30 Days), Month (By Date), Year		Yes, when doRepeat is true	Frequency unit at which the repeat event will be set.
repeatTimes			Yes, when doRepeat is true	Number of times the repeat event will be set to repeat.

//API Call to add a new event (with some example data)

		https://www.pinknotes.com/api/calendarSaveItem?

                 action=add

                 &calendarId=999

                 &sDate=1/21/2014

                 &eDate=1/21/2014

                 &sTime=9:00 AM

                 &eTime=9:30 AM

                 &title=Morning Meeting

//API Call to edit an event (with some example data)

		https://www.pinknotes.com/api/calendarSaveItem?

                 action=edit

                 &calendarId=999

		         &calEventId=123

                 &sDate=1/21/2014

                 &eDate=1/21/2014

                 &sTime=10:00 AM

                 &eTime=10:30 AM

                 &title=Morning Meeting

Delete Calendar Event

Back to top

When your software wants to delete a calendar event you must use the /api/deleteCalendarItem API.

//API Call to delete a calendar event

		https://www.pinknotes.com/api/deleteCalendarItem?

		         id=[CALENDAR EVENT ID]

General Settings

Fetch Account Information

Back to top

To retrieve a list account infromation variables for the account of the logged in user, use the /api/getAccount API. Most of the fields are self explanitory.

The subscriptionStatus value can be one of the following:

Trial - Currently in account trial period
Active - Active, paid account
Free - Active, basic account
Inactive - Once an 'Active' paid account, but now inactive
Inactive Trial - Never 'Active' paid account. Signed up for trial and never upgraded account

//API Call to get all active users for a PinkNotes® acount

		https://www.pinknotes.com/api/getAccount

//Generic Success Response From Server

Fetch Account Users

Back to top

To retrieve a list of all active users for the account of the logged in user, use the /api/getUsers API.

//API Call to get all active users for a PinkNotes® acount

		https://www.pinknotes.com/api/getUsers

//Generic Success Response From Server

Fetch Single User

Back to top

To retrieve a single user for the account of the logged in user, use the /api/getUser API.

//API Call to get a single user for a PinkNotes® acount

		https://www.pinknotes.com/api/getUser?id=[THE USER'S ID]

//Generic Success Response From Server

Logging In

Validating Users & Cookie Creation

Back to top

When your Software wants to interface to the PinkNotes® Messaging System in any way, you must first login the desired user. This is done using the /api/loginDo API.

//API Call to Log a user into PinkNotes®
//All Fields are required®

		https://www.pinknotes.com/api/loginDo?

		         username=[USER'S USERNAME]

		         &password=[USER'S PASSWORD]

		         &account=[USER'S ACCOUNT TAG]

		         &dk=[YOUR DEVELOPER KEY]

//Generic Success Response From Server

//Generic Failure Response From Server

API Overview

General Overview

Back to top

The PinkNotes API allows 3rd party developers access to PinkNotes from their own software in order to accomplish popular tasks on the PinkNotes platform. Such tasks include sending & receiving of PinkNotes, the retrieval of live user information, and much more!

Requests are sent to the server in the form of secure HTTPS requests. 99% of the API calls require that they are being made by a logged in user. That is to say that the /api/loginDo API has been called and successfully executed with no error.

//Get all active users for the account of the currently logged in user

		https://www.pinknotes.com/api/getUsers

While data is sent via HTTPS requests, data is returned from the PinkNotes messaging platform in JSON format. If you are unfamiliar with JSON, please take 5 minutes and study the Basic JSON Schema. It will help you tremendously. Note: Passwords are never present in JSON responses.

//Response From Server
//The following is SAMPLE data. Please login to view live data

Before Getting Started

Back to top

Before getting started, you must acquire your account's Developer Key. This can only be obtained by a user who has Administrative Rights by visiting their Administrative Settings. Once you find the key, we suggest that you include it in your project as a constant for future use.

Sample Send & Receive Functions

Back to top

It is important to note that once a login request is made and validated, a cookie is stored in association with that user's session. Once a user logs in using /api/loginDo, all subsequent API calls must retain the original cookie/session association. This concept will be discussed further, later, in the documentation area "Logging In".

When a request is made, the corresponding data is automatically returned (as a JSON string) so we can Send a Request and receive the appropriate data in one neat function.

//C# Example - A Function to Send/Receive while maintaining cookies by creating a CookieContainer
//C# Example - Example Usage To Get JSON for /api/getUsers

Reciving PinkNotes™

Fetch Message Folders

Back to top

To retrieve a list of all Message Folders for the logged in user, use the /api/getFolders API.

//API Call to get logged in user's PinkNotes® Groups

		https://www.pinknotes.com/api/getFolders

//Generic Success Response From Server

Fetch PinkNote™ Counts

Back to top

Fetch PinkNotes™

Back to top

Sending PinkNotes™

Fetch Userlist

Back to top

To retrieve a list of all active users on the logged in user's userlist (in their desired order) use the /api/getUsers API again, but this time, pass a userlist value to it.

//API Call to fetch a user's PinkNotes userlist
//if userlist contains any value, it is assumed true

		https://www.pinknotes.com/api/getUsers?

		         userlist=[ANY VALUE]

//Generic Success Response From Server

Fetch Groups

Back to top

To retrieve a list of all User Groups and Global Groups for a the logged in user, use the /api/getGroups API.

//API Call to get logged in user's PinkNotes Groups

		https://www.pinknotes.com/api/getUsers

//Generic Success Response From Server

Fetch Field Captions

Back to top

To retrieve a list of fields (types and captions) in order to populate your sending mechanism to the user's specifications, use /api/getMessageFieldCaptions API.

//API Call to get logged in user's PinkNotes Groups

		https://www.pinknotes.com/api/getMessageFieldCaptions

//Generic Success Response From Server
//T=Text Field
//C=Checkbox Field

Sending A PinkNote™

Back to top

To send a quick PinkNote, use the /api/sendPinkNote API. If you want to establish a new login, you must set the login variable to true, otherwise a previous session will be used, if one exists.

API Field Description

Field	Values	Default	Required	Description
login	true or false	false	Yes	If true, a new login session will be created for the sending of the message, and the login session will be terminated upon completion/error. All login credentials (shown below in yellow) must be provided. Typically, true is used for the one-time sending of a message, like an alert from a third-party service. If false, a previous login session will be used if it is available. All login credentials (shown below in yellow) should be omitted. Typically, false is used as part of a larger PinkNotes™ platform (like a third party client) that aready has a session established from the initial login.
username			Yes (when login=true)	The URL-Encoded username of the user the PinkNote™ is being sent by
password			Yes (when login=true)	The URL-Encoded password of the user the PinkNote™ is being sent by
account			Yes (when login=true)	The URL-Encoded account tag of the account the user the PinkNote™ is being sent by belongs to
dk			Yes	The Developer Key for the Developer of the software requesting the data
subject			Yes	The URL-Encoded subject text for the PinkNote™ being sent
msgText			Yes	The URL-Encoded message text for the PinkNote™ being sent
toUser1			Yes	The URL-Encoded username of the first user the PinkNote™ is being sent to
toUser2, etc..				The URL-Encoded username of the 2nd (etc...) user the PinkNote™ is being sent to
fieldId1				The numeric ID of the 1st Message Field we are setting the value for
fieldValue1			Only if fieldId1 is set	The value of the 1st Message Field we are setting the value for. If the field is a type T-Text, this must be a URL-Encoded string. If the field is a type C-Checkbox, the value should be the string "on" to have the field checked, or "off" to have the field unchecked
fieldId2, etc..				The numeric ID of the 2nd (etc...) Message Field we are setting the value for
fieldValue2, etc..			Only if fieldId2 (etc...) is set	The value of the 2nd (etc...) Message Field we are setting the value for. If the field is a type T-Text, this must be a URL-Encoded string. If the field is a type C-Checkbox, the value should be the string "on" to have the field checked, or "off" to have the field unchecked

Field Values that are type Text (T) expect a url encoded string, and fields of type Checkbox (C) can be omitted if they should not checked, or set to 'on' if they should be checked.

Bold variables are required!

//API Call to Send a PinkNote™

		https://www.pinknotes.com/api/sendPinkNote?
login=true

                 &dk=[DEVELOPER'S DEVELOPER KEY]

                 &username=[SENDER'S USERNAME]

                 &password=[SENDER'S PASSWORD]

                 &account=[SENDER'S ACCOUNT TAG]

                 &subject=[URL ENCODED SUBJECT TEXT]

                 &msgText=[URL ENCODED MESSAGE TEXT]

                 &toUser1=[USERNAME OF 1ST RECIPIENT]

                 &toUser2=[USERNAME OF 2ND RECIPIENT]

                 &fieldId1=[ID OF THE 1ST FIELD WE ARE SETTING THE VALUE FOR]

                 &fieldValue1=[URL ENCODED VALUE OF THE 1ST FIELD]

                 &fieldId2=[ID OF THE 2ND FIELD WE ARE SETTING THE VALUE FOR]

                 &fieldValue2=[URL ENCODED VALUE OF THE 2ND FIELD ]

                 &fieldId3=[ID OF THE 3RD FIELD WE ARE SETTING THE VALUE FOR]

                 &fieldValue3=[URL ENCODED VALUE OF THE 3RD FIELD]

//API Call (with actual values) to Send a PinkNote™

		https://www.pinknotes.com/api/sendPinkNote?
login=true

                 &dk=XXXXXXXXXXXXXXXXXXXXXXXXXX

                 &username=bob

                 &password=pickles1999

                 &account=fakeAccountTag

                 &subject=Order+Received

                 &msgText=A+website+order+has+been+received

                 &toUser1=Jason

                 &toUser2=Kristin

                 &toUser3=Warehouse

                 &fieldId1=1

                 &fieldValue1=3+Line+Items+for+%2419.99

                 &fieldId2=6

                 &fieldValue2=on

//Generic Success Response From Server

//Generic Failure Response From Server

Developer API Information