Prayer Cloud API

Empowering your ministry in the cloud

Create a Prayer

Field Type Required Description
church_uuid string Yes The UUID of the church the prayer belongs to
name string Yes The name of the person submitting the prayer
email string Yes The email address of the person submitting the prayer. This email is used to send transactional messages about the persons prayer.
phone string No The phone number of the person submitting the prayer.
prayer string Yes The prayer itself
syndication_type enum Yes How should the prayer be shared on the prayer cloud platform.
authorization_type string Yes How should the information be shared to the church on the prayer cloud platform.
email_updates bool Yes Does the user want to be updated about prayer aknowledgements. The person can always unsubscribe later.

To create a new prayer you will submit an authenticated POST request to https://prayer.ministrycloud.com/api/prayers with the following json form data

{
  "church_uuid": "8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "555-555-5555",
  "prayer": "Prayers for the hurting people in the world.",
  "syndication_type": "syndicate publicly",
  "authorization_type": "authorized publicly",
  "email_updates": true
}

If successful you will recieve a 201 response with the following JSON body.

{
  "data": {
    "uuid": "8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "555-555-5555",
    "prayer": "Prayers for the hurting people in the world.",
    "share_type": [
      "syndicate publicly",
      "authorized publicly"
    ],
    "email_updates": true,
    "acknowledgment_count": 0
  },
  "links": {
    "path": "https://prayer.ministrycloud.com/api/prayers/8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f",
    "acknowledge_prayer_link": "https://prayer.ministrycloud.com/api/acknowledgements/8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f"
  },
  "meta": {
    "status": {
      "state": "unapproved",
      "approved_at": null
    },
    "posted_at": {
      "date": "2018-08-08 23:38:34.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "church": {
      "data": {
        "uuid": "8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11",
        "name": "Simple Site",
        "contacts": [
            {
                "email": "office@simplesite.com",
                "created_at": {
                    "date": "2018-08-08 22:30:12.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "updated_at": {
                    "date": "2018-08-08 22:30:12.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                }
            }
        ],
        "address": {
          "postal_code": "92110"
        }
      },
      "meta": {
        "member_since": {
          "date": "2018-08-08 22:25:20.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "admins": [
          {
            "name": "Ekklesia 360",
            "contact": {
              "email": "engineering@monkdevelopment.com"
            }
          }
        ]
      }
    }
  }
}

Prayer Permissions

There are a variety of permissions and states that a prayer can have within the Prayer Cloud system.


Syndication Types

Syndication Types dictate are how the prayer will be displayed when an unauthenticated request is made for the prayer.

Name Description
syndicate publicly - The Prayer is displayed in the request
- The Contact information is displayed in the request
syndicate anonymously - The Prayer is displayed in the request
- The name is displayed as anonymous
- The email and phone are returned as null
syndicate info only - The Prayer is returned as null
- The Contact information is displayed in the request
unsyndicated - Will return a 404 if viewed directly
- Will not be included in a response of all prayers for a church

Authorization Types

Authorization Types dictate are how the prayer will be displayed when an authenticated request is made for the prayer.

Name Description
authorized publicly - The Prayer is displayed in the request
- The Contact information is displayed in the request
authorized anonymously - The Prayer is displayed in the request
- The name is displayed as anonymous
- The email and phone are returned as null

Approving and Unapproving a Prayer

Prayers always start as unapproved and must be approved by the church. Once a prayer is approved, it will be available for syndication.

Approving

To approve a prayer with the API you will submit an authenticated POST request to https://prayer.ministrycloud.com/api/approval/{{uuid}}.
{{uuid}} is the prayer's UUID.


$url = "https://prayer.ministrycloud.com/api/approval/8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f";
$response = Requests::post($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
));

if ($response->success !== true) {
  throw new Exception('There was an error marking this prayer as Approved.');
}

Unapproving

To unapprove a prayer with the API you will submit an authenticated DELETE request to https://prayer.ministrycloud.com/api/approval/{{uuid}}.
{{uuid}} is the prayer's UUID.


$url = "https://prayer.ministrycloud.com/api/approval/8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f";
$response = Requests::delete($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
));

if ($response->success !== true) {
  throw new Exception('There was an error marking this prayer as Unapproved.');
}

Bulk Approving

To approve a group of prayers at the same time with the API you will submit an authenticated POST request to https://prayer.ministrycloud.com/api/bulk/approval/. 


$url = "https://prayer.ministrycloud.com/api/bulk/approval/";
$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11', // Church UUID
  'prayers' => array(
    '8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f', // Prayer UUID
    '8b7ee5s0-a687-4c45-a311-23ec2aaa2sdsa' // Prayer UUID
  )
);
$response = Requests::post($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
), $data);

if ($response->success !== true) {
  throw new Exception('There was an error marking these prayers as Approved.');
}

You can also remove prayers from the body to approve all of the prayers for the church.

$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11' // Church UUID
);

Bulk Unapproving

To unapprove a group of prayers at the same time with the API you will submit an authenticated PATCH request to https://prayer.ministrycloud.com/api/bulk/approval/. 


$url = "https://prayer.ministrycloud.com/api/bulk/approval/";
$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11', // Church UUID
  'prayers' => array(
    '8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f', // Prayer UUID
    '8b7ee5s0-a687-4c45-a311-23ec2aaa2sdsa' // Prayer UUID
  )
);
$response = Requests::patch($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
), $data);

if ($response->success !== true) {
  throw new Exception('There was an error marking these prayers as Unapproved.');
}

You can also remove prayers from the body to unapprove all of the prayers for the church.

$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11' // Church UUID
);

Deleting a Prayer

Prayers can be deleted with the API by sending an authenticated DELETE request to https://prayer.ministrycloud.com/api/prayers/{{uuid}}.
{{uuid}} is the prayer's UUID.
Once a prayer is deleted, it cannot be recovered. 

$url = "https://prayer.ministrycloud.com/api/prayers/8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f";
$response = Requests::delete($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
));

if ($response->success !== true) {
  throw new Exception('There was an error while deleting this prayer.');
}

Bulk Delete

To delete a group of prayers at the same time with the API you will submit an authenticated DELETE request to https://prayer.ministrycloud.com/api/bulk/destroy/.


$url = "https://prayer.ministrycloud.com/api/bulk/destroy/";
$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11', // Church UUID
  'prayers' => array(
    '8b7ee6a0-b483-4c45-ae41-eec2aaaadd8f', // Prayer UUID
    '8b7ee5s0-a687-4c45-a311-23ec2aaa2sdsa' // Prayer UUID
  )
);
$response = Requests::delete($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
), $data);

if ($response->success !== true) {
  throw new Exception('There was an error deleting these prayers');
}

You can also remove prayers from the body to delete all of the prayers for the church.

$data = array(
  'church' => '8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11' // Church UUID
);

Viewing All Prayers for a Church

While the API will return the same structure for authenticated/unauthenticated requests, the content within each prayer will be dictated by the prayers syndication_type (unauthenticated) and authorization_type (authenticated).
If an unauthenticated request is made for a churches prayers and the syndication_type is unsyndicated then the prayer will not be included in the response.
When requesting a list of prayers, the following filters can be added to the request as query parameters.

Filter How to use Description
status /prayers?filter[status]=approved You can filter by approved and unapproved prayers.
This filter only works on authenticated requests.
limit /prayers?limit=3 You can limit the number of prayers returned with the request.
If no limit is included in the request, 15 prayers will be included in the response.
page /prayers?page=2 Go to a specific page within the paginated response. 
//Authenticated Request
$url = "https://prayer.ministrycloud.com/api/churches/{church-uuid}/prayers";
$response = Requests::get($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
));

The JSON response looks like the following

{
  "data": [
    {
      "data": {
        "uuid": "8b7cdbba-1c9d-450b-a4be-17d0e7c0a546",
        "name": "Alvena Miller",
        "email": "guy.buckridge@example.com",
        "phone": "329.600.3335 x1114",
        "prayer": "Prayers for my daughter who is starting college.",
        "share_type": [
          "syndicate publicly",
          "authorized publicly"
        ],
        "email_updates": false,
        "acknowledgment_count": 5
      },
      "links": {
        "path": "https://prayer.ministrycloud.com/api/prayers/8b7cdbba-1c9d-450b-a4be-17d0e7c0a546",
        "acknowledge_prayer_link": "https://prayer.ministrycloud.com/api/acknowledgements/8b7cdbba-1c9d-450b-a4be-17d0e7c0a546?"
      },
      "meta": {
        "status": {
          "state": "approved",
          "approved_at": {
            "date": "2018-08-07 23:46:56.000000",
            "timezone_type": 3,
            "timezone": "UTC"
          }
        },
        "posted_at": {
          "date": "2018-08-04 00:49:17.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    },
    {
      "data": {
        "uuid": "8b7cdbb9-e3ed-4a72-9618-ed63bb052b30",
        "name": "Myrtie Bernier",
        "email": "margarette42@example.org",
        "phone": "704-684-5635 x56000",
        "prayer": "Prayers for my sister who is going through cancer treatment.",
        "share_type": [
          "syndicate publicly",
          "authorized publicly"
        ],
        "email_updates": false,
        "acknowledgment_count": 0
      },
      "links": {
        "path": "https://prayer.ministrycloud.com/api/prayers/8b7cdbb9-e3ed-4a72-9618-ed63bb052b30",
        "acknowledge_prayer_link": "https://prayer.ministrycloud.com/api/acknowledgements/8b7cdbb9-e3ed-4a72-9618-ed63bb052b30"
      },
      "meta": {
        "status": {
          "state": "unapproved",
          "approved_at": null
        },
        "posted_at": {
          "date": "2014-06-27 08:29:40.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    }
  ],
  "meta": {
    "church": {
      "data": {
        "uuid": "b7ecc6f-e5a3-4998-b04e-483d8ec0bc11",
        "name": "Simple Site",
        "contacts": [
            {
              "email": "office@simplesite.com",
              "created_at": {
                  "date": "2018-08-08 22:30:12.000000",
                  "timezone_type": 3,
                  "timezone": "UTC"
              },
              "updated_at": {
                  "date": "2018-08-08 22:30:12.000000",
                  "timezone_type": 3,
                  "timezone": "UTC"
              }
            }
        ],
        "address": {
          "postal_code": "92110"
        }
      },
      "meta": {
        "member_since": {
          "date": "2018-08-07 01:11:20.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "admins": [
          {
            "name": "Ekklesia 360",
            "contact": {
              "email": "engineering@monkdevelopment.com"
            }
          }
        ]
      }
    },
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "path": "https://prayer.ministrycloud.com/api/churches/8b7b01d6-db16-4d25-b125-53b6c0bd9bc1/prayers",
    "per_page": "2",
    "to": 2,
    "total": 4
  },
  "links": {
    "first": "https://prayer.ministrycloud.com/api/churches/8b7b01d6-db16-4d25-b125-53b6c0bd9bc1/prayers?page=1",
    "last": "https://prayer.ministrycloud.com/api/churches/8b7b01d6-db16-4d25-b125-53b6c0bd9bc1/prayers?page=2",
    "prev": null,
    "next": "https://prayer.ministrycloud.com/api/churches/8b7b01d6-db16-4d25-b125-53b6c0bd9bc1/prayers?page=2"
  }
}

Viewing an Individual Prayer

While the API will return the same structure for authenticated/unauthenticated requests, the content within the prayer will be dictated by the prayers syndication_type (unauthenticated) and authorization_type (authenticated).
If an unauthenticated request is made for a prayer and the syndication_type is unsyndicated then a 404 will be returned.

//Authenticated Request
$url = "https://prayer.ministrycloud.com/api/prayers/{prayer-uuid}";
$response = Requests::get($url, array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer your-api-token',
));

The JSON response looks like the following

{
  "data": {
    "uuid": "8b7cdbba-1c9d-450b-a4be-17d0e7c0a546",
    "name": "Alvena Miller",
    "email": "guy.buckridge@example.com",
    "phone": "329.600.3335 x1114",
    "prayer": "Prayers for my daughter who is starting college.",
    "share_type": [
      "syndicate publicly",
      "authorized publicly"
    ],
    "email_updates": false,
    "acknowledgment_count": 5
  },
  "links": {
    "path": "http://prayer-cloud.local/api/prayers/8b7cdbba-1c9d-450b-a4be-17d0e7c0a546",
    "acknowledge_prayer_link": "http://prayer-cloud.local/api/acknowledgements/8b7cdbba-1c9d-450b-a4be-17d0e7c0a546"
  },
  "meta": {
    "status": {
      "state": "approved",
      "approved_at": {
        "date": "2018-08-07 23:46:56.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    },
    "posted_at": {
      "date": "2016-03-04 00:49:17.000000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "church": {
      "data": {
        "uuid": "8b7ecc6f-e5a3-4998-b04e-483d8ec0bc11",
        "name": "Simple Site",
        "contacts": [
            {
                "email": "office@simplesite.com",
                "created_at": {
                    "date": "2018-08-08 22:30:12.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                },
                "updated_at": {
                    "date": "2018-08-08 22:30:12.000000",
                    "timezone_type": 3,
                    "timezone": "UTC"
                }
            }
        ],
        "address": {
          "postal_code": "92110"
        }
      },
      "meta": {
        "member_since": {
          "date": "2018-08-07 01:11:20.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "admins": [
          {
            "name": "Ekklesia 360",
            "contact": {
              "email": "engineering@monkdevelopment.com"
            }
          }
        ]
      }
    }
  }
}