home

MinistryPlatform

RealmRealm AccountingMinistryPlatformeGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite
RealmRealm AccountingMinistryPlatformeGivingPDSACSConnectShepherdGrowth MethodHeadMasterRefresh WebsitesTrust CenterGo MethodMissionInsite

What would you like to know more about?

Show Contents

thumbnailMinistryPlatform

REST API

Tables

The Tables endpoint allows you to read, update, and create Platform records using the REST API.

Reading Records: GET

Want to retrieve (but not alter) the contents of a table? The GET verb is the verb for you.

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'

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 specific number of records
Returns the top five contacts, or returns 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 and 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 and 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 Records: POST

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
    }
  }
]
Created 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
	}
  }
]

Updating Records: PUT

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"
		}
	}
]

Deleting Records: DELETE

Warning: If you have rights to delete in the Platform, there is nothing to stop you from deleting records using the API. Proceed with great caution. And remember that with great power comes great responsibility.

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
}
Developer (API)
MinistryPlatform
Administrator
SPoC
portal

Last updated: May 17, 2024