The Tables endpoint allows you to read, update, and create Platform records using the REST API.
Want to retrieve (but not alter) the contents of a table? Great! The GET verb is the verb for you. Here's how:
Get a List of Tables: Returns all tables that the user has access to
GET tables/
Get all Records in a Table: Returns all records in a specified table
GET tables/contacts/
Get a Specific Record: Returns a single record from a given table, specified by the primary key value
GET tables/contacts/1
Get a Filtered List: Returns all records that match the filter requirements
GET tables/contacts?$Filter=Last_Name='Administrator'
Get a Filtered List: Returns all records that match the filter requirements. Boolean logic is accepted in the filter.
GET tables/contacts?$Filter=Last_Name='Administrator'
GET tables/contacts?$Filter=(Last_Name='Smith' AND Last_Name='Bob') OR Last_Name='Administrator
Get Only Specific Fields: Returns the specified fields on the requested record(s)
GET tables/contacts/1?$Select=First_Name, Last_Name
Select and Join Another Table: Returns all contact fields, joins the Household table, and gets the linked Household_Name
GET tables/contacts/1?$Select=Contacts.*, Household_ID_Table.Household_Name
Get a Specified Number of Records: Returns the top five contacts or return the top five contacts after skipping the first five
GET tables/contacts?$Top=5
GET tables/contacts?$Top=5&$Skip=5
Get a Distinct Record Set: Returns a distinct list of all cities
GET tables/addresses?$Select=City&$Distinct=true
Order a Record Set: Orders the response by the specified column
GET tables/addresses?$OrderBy=City
Get Records and Group by Column with an Aggregate Function: Selects all donations, sums the Donation_Amount, and groups by Donor_ID
GET tables/donations?$Select=Donor_ID,SUM(Donation_Amount) AS Amount&$GroupBy=Donor_ID
Get Records Using POST Method: Returns all records that match the specified requirements, allowing for long Filter or Select clauses, or retrieving by primary key. Like other table retrieval calls, you can specify: Select, Filter, OrderBy, GroupBy, Having, Top, Skip, Distinct. Tip: If you're using Filter, do not include Ids, which will just give you a specific record, but with multiple primary keys.
POST tables/contacts/get
{ "Ids": [ 1, 2, 3 ], "Select": "Last_Name,First_Name", "Filter": "Last_Name='Administrator'", "OrderBy": "Last_Name", "GroupBy": "Last_Name", "Having": "Last_Name='Administrator'", "Top": 5, "Skip": 2, "Distinct": true }
Get Record & Include Audit Log Creation Data: Returns all contact fields and joins audit log creation data
GET tables/contacts/1?$Select=Contacts.*, dp_Created.*
Get Record & Include Audit Log Update Data: Returns all contact fields and joins audit log update data
GET tables/contacts/1?$Select=Contacts.*, dp_Updated.*
Get the Default Image for a Record: Returns the file guid for the default image of the given record
GET tables/contacts/1?$Select=dp_fileUniqueId
Creating a new record? Use the POST verb.
Create a Single Record: To create a single record, POST an array containing a single JSON object with all fields that should be included for the new record. All fields that do not allow nulls and do not specify a default value are considered required.
POST tables/households
[ { Household_Name: "Household, Test", Home_Phone: "123-456-7890" } ]
Create a Series of Records: To create a multiple records, POST an array containing JSON objects for each record you would like to create.
POST tables/households
[ { Household_Name: "Household, First", Home_Phone: "123-456-7890" }, { Household_Name: "Household, Second", Home_Phone: "098-765-4321" } ]
Create a Record as a Specific User: To create a record as a specific user, specify the user id using the $User keyword in the query string.
POST tables/households?$User=96
[ { Household_Name: "Household, Test", Home_Phone: "123-456-7890" } ]
Create a Nested set of Records: To create a nested set of records, assign a JSON object to a field with a foreign key relationship to another table. This will create both a new household and an address linked to the household.
POST tables/households
[ { Household_Name: "Household, Test", Address_ID: { Address_Line_1: "123 Test St.", City: "TestCity", "State/Region": "TX", Postal_Code: 73301 } } ]
Create Nested Dependent Records: A contact needs to exist to link the participant to and the REST API starts at the deepest level of the nesting structure and works backwards. To make this work you need to invert the nesting. This works because a contact record is not required to have a participant. The Contact gets created first, and its ID gets passed into the participant record when it is created. Note: It will not work to to create the contact record before the participant record.
POST tables/participants
[ { Participant_Type_ID: 4, Participant_Start_Date: "2016-03-15 09:23:51.000", Contact_ID: { First_Name: "Test", Last_Name: "Contact", Display_Name: "Contact, Test", Company: false } } ]
If you need to update a record a table, use the PUT verb.
Update a Single Record: PUT an array containing a single JSON object with the primary key value of the record you would like to change, and any fields that should update.
PUT tables/households
[ { Household_ID: 1234, Home_Phone: "123-456-7890" } ]
Update a Series of Records: PUT an array containing JSON objects for each record you would like to update.
PUT tables/households
[ { Household_ID: 1234, Home_Phone: "123-456-7890" }, { Household_ID: 1235, Home_Phone: "098-765-4321" } ]
Update a Record as a Specific User: Specify the user id using the $User keyword in the query string.
PUT tables/households?$User=96
[ { Household_ID: 1234, Home_Phone: "123-456-7890" } ]
Update a Nested Set of Records: When using nesting and updating records you'll need to supply a primary key for each nested object.
[ { Contact_ID: 1234, Household_ID: { Household_ID: 1234, [This value is required] Household_Name: "Steve's Household" } } ]
If you need to remove records from a table, the DELETE verb will work.
Delete a Single Record: Deletes one record specified by primary key value
DELETE tables/households/116022
Delete Multiple Records: Deletes multiple records. Note: Unlike deleting a single record, this uses an HTTP POST instead of DELETE. You may also specify a User ID to delete as a specific MinistryPlatform user.
POST tables/households/delete
{
"Ids": [
116022,
116023,
116024
],
"User": 96
}